从Swagger API文档生成PDF

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

但是，只能在特定服务器上访问Swagger的服务。如果我想脱机工作，有人知道如何使用Swagger UI创建静态PDF并使用它吗？此外，PDF易于与无法访问服务器的人员共享。

非常感谢！

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

1. 隐藏编辑器窗格
2. 打印预览（我使用过firefox，其他也不错）
3. 更改其页面设置并打印为pdf

我想出了一种使用https://github.com/springfox/springfox和 https://github.com/RobWin/swagger2markup的方法

使用Swagger 2实施文档。

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

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

1. rest-api-> swagger.json：swagger-maven-plugin
2. swagger.json-> Asciidoc：swagger2markup-maven-plugin
3. Asciidoc-> 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插件适用于生成的文档-因此，您必须确保这些插件已在较早的阶段执行。

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

编辑

如果您在使用SwDoc时遇到任何问题（例如pdf生成不完整），最好在此处验证您的json规范：http：//editor.swagger.io/。

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

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

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