如何在Jenkins构建流程中发布SpringFox生成的Swagger静态文档？

当然可以！完全能在Jenkins构建阶段生成SpringFox Swagger的静态文档，之后就能轻松发布到指定位置。我给你分享几个实战派的方案，都是在CI流水线里验证过的：

这个工具能把SpringFox输出的Swagger JSON/YAML转换成Markdown、Asciidoc格式，还能进一步转成HTML或PDF，非常适合流水线自动化。

第一步：项目中配置依赖和插件 #

在你的SpringBoot项目pom.xml里添加以下配置：

<!-- Swagger2Markup 核心依赖 -->
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
    <scope>test</scope>
</dependency>

<!-- Maven插件，用于构建时生成文档 -->
<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <executions>
        <execution>
            <phase>test</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
            <configuration>
                <!-- 指向SpringBoot应用的Swagger API地址 -->
                <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                <!-- 生成文档的输出目录 -->
                <outputDir>${project.build.directory}/swagger-docs</outputDir>
                <!-- 指定生成格式为Markdown，也可以选ASCIIDOC -->
                <config>
                    <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
                </config>
            </configuration>
        </execution>
    </executions>
</plugin>

第二步：Jenkins流水线中的执行逻辑 #

你需要在流水线里先启动SpringBoot应用，确保Swagger接口能访问，再触发文档生成：

stage('Generate Swagger Docs') {
    steps {
        // 构建项目
        sh 'mvn clean package -DskipTests'
        // 后台启动SpringBoot应用
        sh 'nohup mvn spring-boot:run &'
        // 等待应用完全启动（时间按需调整）
        sh 'sleep 15'
        // 执行生成文档的插件命令
        sh 'mvn swagger2markup:process-swagger'
        // 停止应用
        sh 'pkill -f "spring-boot:run"'
    }
}

如果不想启动应用，也可以先导出Swagger JSON到本地，再用插件处理：

# 先拉取Swagger JSON到本地
curl http://localhost:8080/v2/api-docs -o target/swagger-api.json

然后把插件配置里的swaggerInput改成${project.build.directory}/swagger-api.json即可。

如果想要保留Swagger UI的交互体验，可以直接把Swagger UI的静态文件和你的API文档绑定：

1. 下载Swagger UI的静态包（取官方仓库里的dist目录内容），放到项目src/main/resources/static/swagger下
2. 修改index.html里的默认接口地址，把url改成你的Swagger JSON路径（比如/v2/api-docs，或者本地JSON文件路径）
3. Jenkins构建时，导出Swagger JSON到指定目录，然后把Swagger UI静态文件和这个JSON一起打包发布到静态服务器即可。

如果你的项目还能调整依赖，SpringDoc是SpringFox的升级版，支持OpenAPI 3.0，生成静态文档更简洁。比如用它的Maven插件直接导出OpenAPI文档，再转成静态HTML：

<!-- SpringDoc依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

<!-- 生成OpenAPI文档的插件 -->
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.6.0</version>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}</outputDir>
    </configuration>
</plugin>

<!-- 转成静态HTML的插件 -->
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.2.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.build.directory}/openapi.json</inputSpec>
                <generatorName>html</generatorName>
                <output>${project.build.directory}/openapi-html</output>
            </configuration>
        </execution>
    </executions>
</plugin>

生成文档后，在Jenkins流水线里可以用以下方式发布：

• 用archiveArtifacts把文档存到Jenkins的制品库
• 用scp或FTP上传到公司的静态文件服务器
• 提交到Git仓库作为静态文档托管

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