如何在构建流程中生成Swagger的api-docs？

方法一：基于Springfox实现离线生成 #

针对你当前使用的springfox-boot-starter 3.0.0，可以通过编写工具类+Maven插件的方式，在不启动服务器的情况下生成OpenAPI JSON。

步骤1：编写离线生成工具类 #

创建一个Java类，加载Spring上下文的核心部分，直接调用Springfox的API生成OpenAPI文档：

import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.oas.web.OpenApiTransformationContext;
import springfox.documentation.oas.web.WebMvcOpenApiTransformationFilter;
import springfox.documentation.spring.web.plugins.Docket;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.File;
import java.io.IOException;

@Configuration
@ComponentScan(basePackages = "your.swagger.config.package") // 替换为你的Swagger配置所在包
public class OfflineOpenApiGenerator {
    public static void main(String[] args) throws IOException {
        try (AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(OfflineOpenApiGenerator.class)) {
            // 获取Swagger配置的Docket实例
            Docket docket = context.getBean(Docket.class);
            WebMvcOpenApiTransformationFilter filter = context.getBean(WebMvcOpenApiTransformationFilter.class);
            
            // 生成OpenAPI规范对象
            var openApi = filter.transform(
                new OpenApiTransformationContext<>(docket.getDocumentation(), null, null)
            ).getSpecification();
            
            // 将对象写入JSON文件到target目录
            ObjectMapper mapper = new ObjectMapper();
            mapper.writerWithDefaultPrettyPrinter()
                  .writeValue(new File("target/openapi.json"), openApi);
        }
    }
}

注意替换代码中的包路径为你项目实际的Swagger配置包（即定义Docket Bean的包）。

步骤2：配置Maven执行插件 #

在pom.xml中添加exec-maven-plugin，让它在构建的generate-sources阶段执行上面的工具类：

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <id>generate-openapi-json</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>java</goal>
            </goals>
            <configuration>
                <mainClass>your.tool.class.package.OfflineOpenApiGenerator</mainClass> <!-- 替换为工具类全类名 -->
                <classpathScope>compile</classpathScope>
            </configuration>
        </execution>
    </executions>
</plugin>

步骤3：关联DTO生成插件 #

调整你已有的openapi-generator-maven-plugin配置，读取刚生成的target/openapi.json文件：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.6.0</version>
    <executions>
        <execution>
            <id>generate-dtos</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.build.directory}/openapi.json</inputSpec>
                <generatorName>java</generatorName>
                <outputDir>${project.build.directory}/generated-sources/openapi</outputDir>
                <packageName>your.dto.target.package</packageName>
                <configOptions>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

执行mvn clean install时，会先生成OpenAPI JSON，再基于该文件生成DTO，全程无需启动服务器。

方法二：替换为SpringDoc OpenAPI（推荐） #

Springfox已停止维护，SpringDoc是更活跃的替代方案，原生支持离线生成OpenAPI文档，配置更简洁。

步骤1：替换依赖 #

移除springfox-boot-starter，添加SpringDoc的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

步骤2：配置SpringDoc Maven插件 #

在pom.xml中添加插件，直接在构建阶段生成OpenAPI JSON：

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.3</version>
    <executions>
        <execution>
            <id>generate-openapi</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}</outputDir>
        <springBootApplication>your.springboot.main.class</springBootApplication> <!-- 替换为Spring Boot主类全类名 -->
    </configuration>
</plugin>

该插件会加载Spring上下文但不启动服务器，直接生成规范文件。

步骤3：关联DTO生成插件 #

同方法一的第三步，让openapi-generator-maven-plugin读取target/openapi.json即可。

注意事项 #

• 确保Swagger/SpringDoc的配置能扫描到所有API和DTO类，避免生成的文档不完整。
• 若项目有多环境配置，需确保生成文档时使用的是通用配置（比如禁用生产环境的权限拦截器）。

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