SpringFox 3.0.0配置OpenAPI v3却生成Swagger v2文件的问题

• 你的自定义DocumentGenerator组件大概率仍在使用SpringFox中Swagger v2的核心类（比如io.swagger.models.Swagger、Swagger2DocumentationSerializer），而非OpenAPI v3对应的模型和序列化器（org.springframeworkfox.openapi.models.OpenAPI、OpenApi30Serializer）。
• 尽管配置类里指定了DocumentationType.OAS_30，但自定义组件没有正确注入或使用SpringFox为OAS 3.0初始化的文档生成上下文，而是自行实例化了v2版本的生成逻辑。

1. 替换自定义组件中的v2依赖类 #

把自定义DocumentGenerator里和Swagger v2相关的类全部换成OpenAPI v3的对应实现：

• 用org.springframeworkfox.openapi.models.OpenAPI替代io.swagger.models.Swagger
• 用org.springframeworkfox.openapi.web.OpenApi30Serializer处理文档序列化

2. 注入SpringFox官方的OAS 3.0文档构建器 #

在自定义组件中注入SpringFox为OAS 3.0配置好的DocumentationPluginsManager和OpenApiDocumentationProvider，通过它们获取标准的OpenAPI v3格式文档数据：

@Component
public class CustomOpenApiGenerator {

    private final DocumentationPluginsManager docsManager;
    private final OpenApiDocumentationProvider openApiProvider;

    // 构造注入SpringFox提供的核心组件
    public CustomOpenApiGenerator(DocumentationPluginsManager docsManager,
                                  OpenApiDocumentationProvider openApiProvider) {
        this.docsManager = docsManager;
        this.openApiProvider = openApiProvider;
    }

    public String generateOpenApi3Json() {
        // 获取指定分组的API文档（默认分组是"default"，可根据你的配置调整）
        Documentation apiDocs = docsManager.documentationByGroup("default");
        // 转换为OpenAPI v3标准模型
        OpenAPI openApiModel = openApiProvider.get(apiDocs);
        // 序列化为JSON字符串
        ObjectMapper mapper = new ObjectMapper();
        try {
            return mapper.writeValueAsString(openApiModel);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("生成OpenAPI 3.0文档失败", e);
        }
    }
}

3. 确认Swagger配置类无残留v2设置 #

检查你的SwaggerConfig，确保完全基于OAS 3.0配置，没有混入v2的相关代码：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.project.api"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目API文档")
                .version("1.0.0")
                .description("基于OpenAPI 3.0的接口文档")
                .build();
    }
}

4. 清理依赖，避免版本冲突 #

确保项目依赖里只有SpringFox 3.0.0的核心包，不要混入旧版Swagger v2的依赖。比如Maven的pom.xml配置：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

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