[原创文章] Swagger生成pdf格式的接口文档

1. 概述

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

2. 使用 Maven 插件生成 PDF

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

生成所需 PDF 文件的步骤包括在 Maven 构建期间以特定顺序应用多个插件。插件应配置为选择资源并将前一阶段的输出作为下一阶段的输入进行传播。那么，让我们看看它们是如何工作的。

2.1. 该招摇- Maven的插件插件

我们将使用的第一个插件是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>

我们需要指向 API 的位置并定义插件生成swagger.json文件的构建过程中的阶段。在这里，在执行标记中，我们已经指定它应该在打包阶段执行此操作。

2.2. 该swagger2markup - Maven的插件插件

我们需要的第二个插件是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>

在这里，我们指定inputDirectory和 o utputDirectory标签。同样，我们将包定义为为我们的 REST API 生成 Asciidoc 的构建阶段。

2.3. 该asciidoctor - Maven的插件插件

我们将使用的第三个也是最后一个插件是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>

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

3. 使用 SwDoc 生成 PDF

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

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

该解决方案易于使用，如果我们已经拥有 Swagger 2 API 文档，则是一个不错的选择。

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

• 提供我们的swagger.json 文件的 URL
• 将swagger.json文件的内容粘贴到工具的文本框中

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

出于我们的目的，我们将复制 JSON 文件并将其粘贴到文本框中：

然后，在我们单击“生成”按钮后，我们将获得 PDF 格式的文档：

4。结论

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

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

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

与往常一样，这些示例的代码可在 GitHub 上找到。