Question

我使用Swagger UI来显示我的REST Web服务并将其托管在服务器上。

然而，Swagger的这项服务只能在特定服务器上访问。如果我想离线工作，有人知道如何使用Swagger UI创建静态PDF并使用它吗？此外，PDF很容易与无权访问服务器的人共享。

非常感谢！

Answer 1

我找到了一种使用https://github.com/springfox/springfox和。的方式 https://github.com/RobWin/swagger2markup

使用Swagger 2实现文档。

Answer 2

方便：使用浏览器打印/预览

隐藏编辑器窗格
打印预览（我使用的是Firefox，其他人也很好）
更改其页面设置并打印为pdf

Answer 3

您可以修改REST项目，以便在构建项目时生成所需的静态文档（html，pdf等）。

如果您有Java Maven项目，可以使用下面的pom片段。它使用一系列插件来生成pdf和html文档（项目的REST资源）。

rest-api - ＆gt; swagger.json：swagger-maven-plugin
swagger.json - ＆gt; Asciidoc：swagger2markup-maven-plugin
Asciidoc - ＆gt; PDF：asciidoctor-maven-plugin

请注意，由于一个插件的输出成为下一个插件的输入，因此执行顺序很重要：

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>some.package</locations>
                <basePath>/api</basePath>
                <info>
                    <title>Put your REST service's name here</title>
                    <description>Add some description</description>
                    <version>v1</version>
                </info>
                <swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
                <attachSwaggerArtifact>true</attachSwaggerArtifact>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>${phase.generate-documentation}</phase>
            <!-- fx process-classes phase -->
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>io.github.robwin</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>0.9.3</version>
    <configuration>
        <inputDirectory>${project.build.directory}/api</inputDirectory>
        <outputDirectory>${generated.asciidoc.directory}</outputDirectory>
        <!-- specify location to place asciidoc files -->
        <markupLanguage>asciidoc</markupLanguage>
    </configuration>
    <executions>
        <execution>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.11</version>
        </dependency>
        <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>1.7.21</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
        <!-- You will need to create an .adoc file. This is the input to this plugin -->
        <sourceDocumentName>swagger.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>2</toclevels>
            <generated>${generated.asciidoc.directory}</generated>
            <!-- this path is referenced in swagger.adoc file. The given file will simply 
                point to the previously create adoc files/assemble them. -->
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>${generated.html.directory}</outputDirectory>
                <!-- specify location to place html file -->
            </configuration>
        </execution>
        <execution>
            <id>asciidoc-to-pdf</id>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${generated.pdf.directory}</outputDirectory>
                <!-- specify location to place pdf file -->
            </configuration>
        </execution>
    </executions>
</plugin>

asciidoctor插件假定存在一个.adoc文件。您可以创建一个只收集swagger2markup插件创建的那个：

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

如果您希望生成的html文档成为war文件的一部分，则必须确保它存在于顶层 - WEB-INF文件夹中的静态文件将不会提供。你可以在maven-war-plugin中执行此操作：

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <warSourceDirectory>WebContent</warSourceDirectory>
        <failOnMissingWebXml>false</failOnMissingWebXml>
        <webResources>
            <resource>
                <directory>${generated.html.directory}</directory>
            <!-- Add swagger.pdf to WAR file, so as to make it available as static content. -->
            </resource>
            <resource>
                <directory>${generated.pdf.directory}</directory>
            <!-- Add swagger.html to WAR file, so as to make it available as static content. -->
            </resource>
        </webResources>
    </configuration>
</plugin>

war插件适用于生成的文档 - 因此，您必须确保这些插件已在较早阶段执行。

Answer 4

虽然Amaan Mohammed的解决方案看起来会起作用，但有一种更简单的方法可以做到这一点。看看swagger2markup-cli。

Answer 5

我创建了一个专门解决该问题的网站https://www.swdoc.org/。因此，它会按照答案中的建议自动执行swagger.json -> Asciidoc, Asciidoc -> pdf转换。这样做的好处是您不需要执行安装过程。它接受url或原始json形式的规范文档。项目页面为https://github.com/Irdis/SwDoc

Answer 6

检出https://mrin9.github.io/RapiPdf具有很多自定义和本地化功能的自定义元素。

免责声明：我是该软件包的作者

Answer 7

对我来说，最简单的解决方案是将swagger（v2）导入Postman，然后转到Web视图。您可以在此处选择“单列”视图，然后使用浏览器将其打印为pdf。不是自动化/集成解决方案，而是一次性使用。它处理纸张宽度要比从editor2.swagger.io进行打印要好得多，在该情况下，滚动条会导致部分内容被隐藏。

Answer 8

我追求的是相对快速、简单、最少的软件安装。我正在寻找可以粘贴到 word 文档中以表明 API 存在的东西；我不需要任何级别的交互性或复制粘贴操作的能力。

我已经有一个名为 PicPick 的软件，这是一个可以截取滚动窗口的截图工具（它可以滚动、截图和拼接在一起，生成一个非常高的图像）

它也可以另存为 PDF，但效果不佳，纸张大小，所以我通过了 Publisher

运行我启用了 swagger 的 netcore API 项目
浏览器出现了大摇大摆的“试用”页面，足以达到目的
隐藏试用按钮：右键单击“试用”>>“检查元素”>>添加 CSS 类 >> display: none 用于试用
PicPick 托盘图标 >> 捕获 >> 滚动窗口
点击浏览器的内容面板
注意：如果光标一直悬停在窗口上，PP 可能只能滚动窗口 - 至少我是这样发现的
等待一段时间，它会反复滚动、截屏并将图像拼接在一起
将结果另存为 PNG
加载 Publisher，将自定义页面大小设置为（PNG 尺寸除以 96）英寸
插入图片并重置为 100% 大小
另存为 PDF

从Swagger API文档生成PDF

8 个答案: