概述
本教程将介绍从Swagger API文档生成PDF文件的不同方法。若想了解Swagger，请参考我们关于如何使用Spring REST API设置Swagger的教程：设置Swagger 2与Spring REST API。
2. 生成PDF的Maven插件方法
从Swagger API文档生成PDF文件的第一个解决方案是基于一组Maven插件。通过这种方法，我们可以在构建Java项目时获得PDF文件。
生成所需的PDF文件涉及在特定顺序中应用多个插件于Maven构建过程中。这些插件需要配置以选择资源，并将前一阶段的输出作为下一阶段的输入。接下来，我们将逐一了解它们的工作原理。
2.1. swagger-maven-plugin插件
首先使用的插件是[swagger-maven-plugin](https://mvnrepository.com/artifact/com.github.kongchen/swagger-maven-plugin/3.1.8)。此插件为我们的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>
我们需要指定API的位置，并在构建过程中的某个阶段定义插件生成swagger.json文件。在这里，在execution标签中，我们已指定它应在package阶段执行。
2.2. swagger2markup-maven-plugin插件
第二个必需的插件是[swagger2markup-maven-plugin](https://mvnrepository.com/artifact/io.github.swagger2markup/swagger2markup-maven-plugin/1.3.7)。它将前一个插件的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>
在这里，我们指定了inputDirectory和outputDirectory标签。同样，我们将定义package作为为REST API生成Asciidoc的构建阶段。
2.3. asciidoctor-maven-plugin插件
我们将使用的第三个也是最后一个插件是[asciidoctor-maven-plugin](https://mvnrepository.com/artifact/org.asciidoctor/asciidoctor-maven-plugin/2.2.1)。作为三个插件中的最后一个，它将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>
我们提供Asciidoc在前一阶段生成的位置，然后定义生成PDF文档的路径，并指定生成PDF的阶段。再次使用package阶段。
3. 使用SwDoc生成PDF
Swagger to PDF是一个在线工具，可在swdoc.org上找到，它使用提供的swagger.json规范生成API文档的PDF文件。它依赖于Swagger2Markup转换器和AsciiDoctor。
这个解决方案的原理与前一种类似。首先，Swagger2Markup将swagger.json转换为Asciidoc文件。然后，Asciidoctor解析这些文件并将其转换为文档模型，最后生成PDF文件。
如果已经拥有Swagger 2 API文档，这种方法非常方便。
我们可以使用两种方式生成PDF：
- 提供指向
swagger.json文件的URL - 将
swagger.json文件的内容粘贴到工具的文本框中
我们将使用公开可用的PetStore API文档，可以从Swagger获取：Swagger上的PetStore API文档。
为了演示，我们将复制JSON文件并将其粘贴到文本框中：
点击“生成”按钮后，我们将得到PDF格式的文档：
4. 总结
在这篇简短的教程中，我们讨论了从Swagger API文档生成PDF文件的两种方法。
第一种方法依赖于Maven插件。我们可以使用三个插件，在构建应用程序的同时生成REST API文档。
第二种解决方案描述了使用SwDoc在线工具生成PDF文档。我们可以从swagger.json链接或直接粘贴JSON文件内容到工具中生成文档。
如往常一样，这些示例的代码可在GitHub上找到。