基于Springfox-Swagger2，如何在构建阶段生成OpenAPI YAML规范？

你可以通过两种常见方式在Gradle构建流程中生成静态的Swagger/OpenAPI JSON/YAML文件，以下是具体实现步骤：

方案一：通过Spring Boot测试生成（推荐） #

这种方式利用Spring Boot的测试环境启动应用，调用Swagger API端点后保存响应内容，无需担心端口冲突问题。

1. 补充Gradle依赖 #

在build.gradle中添加必要的测试依赖（如果已有可跳过）：

dependencies {
    // 原有依赖...
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.boot:spring-boot-starter-web'
    // 如果需要生成YAML格式，添加Jackson YAML转换器
    testImplementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml'
}

2. 编写测试类创建生成逻辑 #

在测试目录下创建SwaggerStaticGeneratorTest.java：

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class SwaggerStaticGeneratorTest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    public void generateSwaggerJson() throws IOException {
        // 调用你的Swagger API Docs端点
        ResponseEntity<String> response = restTemplate.getForEntity("/v1/api-docs", String.class);
        
        // 验证请求成功
        assert response.getStatusCode() == HttpStatus.OK;
        
        // 指定输出路径，可根据需求修改
        String outputPath = "build/api-docs/swagger.json";
        File outputFile = new File(outputPath);
        outputFile.getParentFile().mkdirs(); // 创建父目录
        
        // 写入JSON文件
        try (FileWriter writer = new FileWriter(outputFile)) {
            writer.write(response.getBody());
        }
    }

    @Test
    public void generateSwaggerYaml() throws IOException {
        ResponseEntity<String> response = restTemplate.getForEntity("/v1/api-docs", String.class);
        assert response.getStatusCode() == HttpStatus.OK;
        
        // 将JSON转换为YAML格式
        ObjectMapper jsonMapper = new ObjectMapper();
        Object swaggerData = jsonMapper.readValue(response.getBody(), Object.class);
        
        ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory());
        String yamlContent = yamlMapper.writeValueAsString(swaggerData);
        
        String outputPath = "build/api-docs/swagger.yaml";
        File outputFile = new File(outputPath);
        outputFile.getParentFile().mkdirs();
        
        try (FileWriter writer = new FileWriter(outputFile)) {
            writer.write(yamlContent);
        }
    }
}

3. 配置Gradle任务 #

在build.gradle中添加自定义任务，执行上述测试：

// 生成Swagger文档的任务
task generateSwaggerDocs(type: Test) {
    // 指定仅执行Swagger生成的测试类
    include '**/SwaggerStaticGeneratorTest.class'
    // 声明输出目录，帮助Gradle识别增量构建
    outputs.dir file('build/api-docs')
}

// 可选：让build任务自动触发文档生成
build.dependsOn generateSwaggerDocs

执行方式 #

运行以下命令即可生成文件：

./gradlew generateSwaggerDocs

生成的文件会存放在build/api-docs目录下。

方案二：通过独立Main类生成 #

如果不想依赖测试环境，可以编写一个独立的Main类启动应用并生成文档：

1. 编写Main类 #

在主源码目录下创建SwaggerGeneratorMain.java：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.web.client.RestTemplate;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;

@SpringBootApplication
public class SwaggerGeneratorMain {
    public static void main(String[] args) throws IOException {
        // 启动Spring应用上下文
        ConfigurableApplicationContext context = SpringApplication.run(SwaggerGeneratorMain.class, args);
        RestTemplate restTemplate = new RestTemplate();
        
        // 调用Swagger端点（注意端口需与应用配置一致，可在application.properties中临时指定）
        String swaggerJson = restTemplate.getForObject("http://localhost:8081/v1/api-docs", String.class);
        
        // 保存JSON文件
        String outputPath = "build/api-docs/swagger.json";
        File outputFile = new File(outputPath);
        outputFile.getParentFile().mkdirs();
        
        try (FileWriter writer = new FileWriter(outputFile)) {
            writer.write(swaggerJson);
        }
        
        // 关闭应用上下文
        context.close();
    }
}

2. 配置Gradle任务 #

在build.gradle中添加执行该Main类的任务：

task generateSwaggerDocs(type: JavaExec) {
    mainClass = 'com.your.package.SwaggerGeneratorMain' // 替换为你的类全路径
    classpath = sourceSets.main.runtimeClasspath
    outputs.dir file('build/api-docs')
}

执行方式 #

运行以下命令：

./gradlew generateSwaggerDocs

注意：这种方式需要确保应用启动端口未被占用，建议在application.properties中临时指定一个专用端口，比如server.port=8081。

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