从Swagger API文档生成PDF

Question

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

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

非常感谢!

Answer 1

方便的方法:使用浏览器打印/预览

1. 隐藏编辑器窗格
2. 打印预览(我使用的是firefox,其他人也很好)
3. 更改其页面设置并打印为pdf

Answer 2

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

使用Swagger 2来实现文档.

Answer 3

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

编辑

如果您对 SwDoc 有任何问题，比如生成的 pdf 不完整，那么在此处验证您的 json 规范可能是个好主意：http : //editor.swagger.io/。

Answer 4

您可以修改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插件适用于生成的文档 - 因此,您必须确保这些插件已在早期阶段执行.

Answer 5

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

免责声明：我是这个包的作者