Spring Boot Maven项目如何用插件从OpenAPI 3生成PDF文档？

当然可以实现，针对OpenAPI 3规范，你需要替换原Swagger 2流程中的部分插件，以下是适配后的完整流程：

步骤1：生成OpenAPI 3规范文件（JSON/YAML） #

原swagger-maven-plugin仅支持Swagger 2，针对OpenAPI 3推荐使用以下插件之一：

• springdoc-openapi-maven-plugin：适合Spring Boot项目，可自动扫描代码生成OpenAPI 3文档
• openapi-generator-maven-plugin：通用型插件，支持从代码或已有规范生成标准OpenAPI文件

示例配置（springdoc版本）：

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.2</version>
    <executions>
        <execution>
            <id>generate-openapi</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}/openapi</outputDir>
            </configuration>
        </execution>
    </executions>
</plugin>

步骤2：将OpenAPI 3文件转换为Asciidoc #

原swagger2markup-maven-plugin已更新支持OpenAPI 3，只需使用最新版本即可：

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <executions>
        <execution>
            <id>convert-swagger-to-asciidoc</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>convertSwagger2markup</goal>
            </goals>
            <configuration>
                <swaggerInput>${project.build.directory}/openapi/openapi.json</swaggerInput>
                <outputDir>${project.build.directory}/asciidoc</outputDir>
                <config>
                    <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                </config>
            </configuration>
        </execution>
    </executions>
</plugin>

步骤3：将Asciidoc转换为PDF #

这一步和原流程一致，使用asciidoctor-maven-plugin：

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.6</version>
    <executions>
        <execution>
            <id>convert-asciidoc-to-pdf</id>
            <phase>package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>${project.build.directory}/asciidoc</sourceDirectory>
                <outputDirectory>${project.build.directory}/pdf</outputDirectory>
                <backend>pdf</backend>
                <attributes>
                    <doctype>book</doctype>
                    <toc>left</toc>
                    <toclevels>3</toclevels>
                </attributes>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.6.2</version>
        </dependency>
    </dependencies>
</plugin>

执行流程 #

运行Maven命令触发整个流程：

mvn clean package

最终生成的PDF文件会存放在target/pdf目录下。

内容的提问来源于stack exchange，提问作者Mostafa Mayou