知識庫 / REST RSS 訂閱

1. 概述

在本教程中，我們將學習如何從 Swagger API 文檔生成 PDF 文件。為了熟悉 Swagger，請參考我們關於設置 Swagger 2 與 Spring REST API 的教程。

2. 使用 Maven 插件生成 PDF

基於 Swagger API 文檔生成 PDF 文件的首選方案是使用一組 Maven 插件。 採用這種方法，在構建 Java 項目時，我們即可獲得 PDF 文件。

生成所需 PDF 文件需要執行以下步驟：在 Maven 構建過程中，需要應用一組插件，並按照特定順序進行操作。 這些插件應配置為在 Maven 構建的各個階段中，選擇資源並作為下一階段的輸入，傳遞前一階段的輸出。 讓我們來看看每個插件的工作原理。

2.1. Swagger Maven 插件

我們將首先使用 Swagger Maven 插件。該插件會生成我們的 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。它接受前一個插件輸出的 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. <em>asciidoctor-maven-plugin</em> 插件

我們將使用的第三個也是最後一個插件是 <em><a href="https://mvnrepository.com/artifact/org.asciidoctor/asciidoctor-maven-plugin/2.2.1">asciidoctor-maven-plugin</a></em>。 作為這三個插件的最後者，它 <strong>生成 PDF 文件，從 Asciidoc 轉換而來</strong>：

<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 上公開。

為了我們的目的，我們將複製 JSON 文件並將其粘貼到文本框中：

 

然後，當我們點擊“生成”按鈕後，我們將獲得文檔的 PDF 格式：

 

4. 結論

在本教程中，我們討論了兩種從 Swagger API 文檔生成 PDF 的方法。

第一種方法依賴於 Maven 插件。我們可以使用三個插件在構建應用程序時生成 REST API 文檔。

第二種解決方案描述了使用 SwDoc 在線工具生成 PDF 文檔的方法。我們可以通過將鏈接到我們的 swagger.json 或將 JSON 文件內容粘貼到工具中來生成文檔。