Generate PDF from Swagger API Documentation – 从Swagger API文档中生成PDF

最后修改: 2021年 12月 11日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

In this tutorial, we’ll get to know different ways of generating a PDF file from Swagger API documentation. To get familiar with Swagger, refer to our tutorial for setting up Swagger 2 with a Spring REST API.

在本教程中，我们将了解从Swagger API文档生成PDF文件的不同方法。要熟悉Swagger，请参考我们的设置Swagger 2与Spring REST API的教程。

2. Generate PDF with Maven Plugins

2.用Maven插件生成PDF

The first solution for generating a PDF file from Swagger API documentation is based on a set of Maven plugins. With this approach, we’ll get the PDF file upon building a Java project.

从Swagger API文档生成PDF文件的第一个解决方案是基于一组Maven插件。通过这种方法，我们在构建一个Java项目时就能得到PDF文件。

The steps for producing the desired PDF file include applying several plugins in a specific order during a Maven build. The plugins should be configured to pick the resources and propagate the outputs from the previous phases as the inputs of the next phase. So, let’s see how each of them works.

生成所需PDF文件的步骤包括在Maven构建过程中按特定顺序应用几个插件。这些插件应被配置为挑选资源，并将前几个阶段的输出作为下一个阶段的输入进行传播。那么，让我们看看它们各自是如何工作的。

2.1. The swagger-maven-plugin Plugin

2.1.swagger-maven-pluginPlugin

The first plugin we’ll use is swagger-maven-plugin. This plugin produces the swagger.json file for our REST API:

我们要使用的第一个插件是swagger-maven-plugin。这个插件为我们的REST API生成swagger.json文件。

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
	    <apiSource>
        	<springmvc>false</springmvc>
		<locations>com.baeldung.swagger2pdf.controller.UserController</locations>
		<basePath>/api</basePath>
		<info>
	            <title>DEMO REST API</title>
		    <description>A simple DEMO project for REST API documentation</description>
		    <version>v1</version>
		</info>
		<swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
	        <attachSwaggerArtifact>true</attachSwaggerArtifact>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
		<goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

We need to point to the locations of our API and define the phase in the build process during which the plugin produces the swagger.json file. Here, in the execution tag, we’ve specified that it should do this during the package phase.

我们需要指出我们的API的位置，并定义插件在构建过程中产生swagger.json文件的阶段。在这里，在execution标签中，我们指定它应该在package阶段进行。

2.2. The swagger2markup-maven-plugin Plugin

2.2.swagger2markup-maven-plugin插件

The second plugin we need is the swagger2markup-maven-plugin. It takes the swagger.json output of the previous plugin as its input to produce Asciidoc:

我们需要的第二个插件是swagger2markup-maven-plugin。它将前一个插件的swagger.json输出作为其输入，生成Asciidoc。

<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>
        <markupLanguage>asciidoc</markupLanguage>
    </configuration>
    <executions>
        <execution>
	    <phase>package</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Here, we specify the inputDirectory and the outputDirectory tags. Again, we’ll define package as the build phase for generating the Asciidoc for our REST API.

这里，我们指定了inputDirectory和outputDirectory标签。同样，我们将定义package作为构建阶段，为我们的REST API生成Asciidoc。

2.3. The asciidoctor-maven-plugin Plugin

2.3.asciidoctor-maven-plugin插件

The third and final plugin we’ll use is the asciidoctor-maven-plugin. As the last of the three plugins, this one produces a PDF file from Asciidoc:

我们要用的第三个也是最后一个插件是asciidoctor-maven-plugin。作为三个插件中的最后一个，这个插件从Asciidoc生成一个PDF文件。

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.1</version>
    <dependencies>
        <dependency>
	    <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.6.0</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${project.build.outputDirectory}/../asciidoc</sourceDirectory>
        <sourceDocumentName>overview.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>2</toclevels>
            <generated>${generated.asciidoc.directory}</generated>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-pdf</id>
            <phase>package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${project.build.outputDirectory}/api/pdf</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

Basically, we provide the location where the Asciidoc was generated during the previous phase. Then, we define a location for it to generate the PDF documentation and specify the phase during which it should generate the PDF. Once again, we’re using the package phase.

基本上，我们提供在前一阶段生成Asciidoc的位置。然后，我们为它定义一个生成PDF文档的位置，并指定它应该在哪个阶段生成PDF。再一次，我们使用package阶段。

3. Generate PDF using SwDoc

3.使用SwDoc生成PDF

Swagger to PDF is an online tool, available at swdoc.org, that generates the API documentation in a PDF file using the provided swagger.json specification. It relies on the Swagger2Markup converter and AsciiDoctor.

Swagger to PDF 是一个在线工具，可在swdoc.org上使用所提供的swagger.json规范生成 PDF 文件中的 API 文档。它依赖于Swagger2Markup转换器和AsciiDoctor。。

The principles are similar to those in the previous solution. First, Swagger2Markup converts swagger.json to AsciiDoc files. Then, Asciidoctor parses those files into a document model and converts them to the PDF file.

其原理与之前的解决方案相似。首先，Swagger2Markup将swagger.json转换为AsciiDoc文件。然后，Asciidoctor将这些文件解析成一个文档模型，并将其转换为PDF文件。

The solution is easy to use and is a good choice if we already have our Swagger 2 API document.

这个解决方案很容易使用，如果我们已经有了我们的Swagger 2 API文档，它是一个很好的选择。

We can generate the PDF in two ways:

我们可以通过两种方式生成PDF。

  • providing a URL to our swagger.json file
  • pasting the contents of our swagger.json file into the tool’s text box

We’ll use the PetStore API doc publicly available on Swagger.

我们将使用PetStore API doc公开提供的Swagger上的。

For our purpose, we’ll copy the JSON file and paste it into the text box:

为了我们的目的，我们将复制JSON文件并将其粘贴到文本框中。

swagger to pdf 1

 

Then, after we click the “Generate” button, we’ll get the documentation in PDF format:

然后，在我们点击 “生成 “按钮后，我们会得到PDF格式的文档。

swagger to pdf 2

 

4. Conclusion

4.总结

In this short tutorial, we’ve discussed two ways to generate PDF from Swagger API documentation.

在这个简短的教程中，我们已经讨论了从Swagger API文档中生成PDF的两种方法。

The first approach relies on Maven plugins. We can use three plugins and generate the REST API documentation while building the application.

第一种方法依赖于Maven插件。我们可以使用三个插件，在构建应用程序时生成REST API文档。

The second solution describes how to generate PDF documents using the SwDoc online tool. We can either generate the documentation from the link to our swagger.json or paste the JSON file contents into the tool.

第二个解决方案描述了如何使用SwDoc在线工具生成PDF文档。我们可以从我们的swagger.json的链接中生成文档，或者将JSON文件内容粘贴到该工具中。

As always, the code for these examples is available over on GitHub.

像往常一样，这些例子的代码可以在GitHub上找到over。