Git Actions CI/CD中Java项目如何将swagger.json转为OpenAPI3规范

针对Java技术栈、Git Actions自动化CI/CD流程下的Swagger2转OpenAPI3场景，你调研的三个方案适配性如下：

• Swagger Inspector：你的判断完全准确，这是纯Web端的人工交互工具，需要手动上传文件、手动触发转换，没有API/命令行调用能力，完全无法集成到自动化流程，直接排除。
• SwaggerHub Gradle插件：这个插件的核心能力是将API规范文件同步到SwaggerHub云平台做托管，格式转换只是附带的边缘功能。如果你团队本身没有在用SwaggerHub做全生命周期的API资产管理，用这个方案需要额外在CI里配置平台密钥、引入第三方服务依赖，冗余度极高，不推荐。
• Swagger Codegen：可以实现格式转换，但属于典型的大材小用。这个工具的核心定位是根据API规范生成多语言客户端/服务端脚手架代码，做格式转换需要依赖几十M的CLI包，CI运行冷启动慢，转换后还会生成一堆无关的工程文件，清理麻烦，不是最优选择。

首推Swagger官方原生的转换工具类，属于swagger-core包自带的能力，零外部服务依赖、包体积小、兼容Java生态所有Swagger2的自定义扩展，完美匹配你的场景。

Gradle项目配置 #

直接在build.gradle中添加独立转换任务即可，不需要改动原有业务依赖：

configurations {
    swaggerConvert
}

dependencies {
    swaggerConvert 'io.swagger.core.v3:swagger-core:2.2.15'
    swaggerConvert 'io.swagger:swagger-models:1.6.9'
    swaggerConvert 'com.fasterxml.jackson.core:jackson-databind:2.15.2'
}

// Swagger2转OpenAPI3任务
task convertSwagger2ToOpenApi3(type: JavaExec) {
    classpath = configurations.swaggerConvert
    mainClass = 'io.swagger.v3.core.converter.Swagger20Converter'
    // 第一个参数是原有swagger.json的生成路径，第二个是转换后openapi.json的输出路径
    args = [
        "$buildDir/docs/swagger.json",
        "$buildDir/docs/openapi.json"
    ]
}

如果是Maven项目，用exec-maven-plugin绑定同一个主类、传相同参数即可，逻辑完全一致。

Git Actions流程集成 #

转换任务和现有CI流程的衔接非常简单，按顺序执行三步即可：

1. 执行项目原有构建任务，生成Swagger2格式的swagger.json
2. 调用上面定义的convertSwagger2ToOpenApi3任务完成格式转换
3. 后续生成接口文档、同步API网关、做接口契约校验等步骤，直接读取输出的openapi.json即可

兼容提示：如果你的swagger.json包含自定义扩展字段，原生转换器会自动保留不会丢失；如果遇到特殊格式兼容问题，直接把swagger-core升级到最新稳定版即可，官方对Swagger2的格式兼容覆盖度很高。

轻量备选方案 #

如果你不想改动项目的构建配置，也可以直接在Git Actions步骤中用Node生态的api-spec-converter命令行工具完成转换，只要CI环境带Node运行时即可，核心命令只有一行：

npx api-spec-converter --from=swagger_2 --to=openapi_3 --syntax=json ./swagger.json > ./openapi.json

这个方案的缺点是转换逻辑不是Java原生实现，遇到Springfox、Swagger2 Java注解生成的特殊扩展字段时，偶尔会出现转换偏差，稳定性不如原生Java转换器。

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