从 Swagger API 文档生成 PDF

Question

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

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

非常感谢！

Answer 1

我想出了一个使用 https://github.com/springfox/springfox 的方法，并且 https://github.com/RobWin/swagger2markup

使用 Swagger 2 来实现文档。

Answer 2

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

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

rest-api -> swagger.json : swagger-maven-plugin
swagger.json -> Asciidoc：swagger2markup-maven-plugin
Asciidoc -> PDF：asciidoctor-maven-plugin

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

<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 3

便捷方式：使用浏览器Printing/Preview

隐藏编辑器窗格
打印预览（我用的是firefox，其他的也可以）
更改其页面设置并打印为 pdf

Answer 4

对我来说，最简单的解决方案是将 swagger (v2) 导入 Postman，然后转到 Web 视图。在那里您可以选择 "single column" 查看并使用浏览器打印为 pdf。不是 automated/integrated 解决方案，但适合一次性使用。它比从 editor2.swagger.io 打印更好地处理纸张宽度，其中滚动条导致部分内容被隐藏。

Answer 5

我创建了一个网站https://www.swdoc.org/ that specifically addresses the problem. So it automates swagger.json -> Asciidoc, Asciidoc -> pdf transformation as suggested in the answers. Benefit of this is that you dont need to go through the installation procedures. It accepts a spec document in form of url or just a raw json. Project is written in C# and its page is https://github.com/Irdis/SwDoc

编辑

最好在此处验证您的 json 规范：http://editor.swagger.io/ 如果您对 SwDoc 有任何问题，例如生成的 pdf 不完整。

Answer 6

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

我已经有一个 软件叫 PicPick，一个截图工具，可以捕获滚动 window（它滚动，截图和拼接在一起生成一个非常高的图片）

它也可以保存为 PDF，但在纸张大小方面做得不好，所以我通过 Publisher 传递了它

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

从 Swagger API 文档生成 PDF

Generate PDF from Swagger API documentation

pdf

swagger-ui