如何在Swagger中管理多版本API并保留各迭代版本的接口？

以下是两种常用场景的具体实现方法：

场景1：纯OpenAPI规范文件独立维护 #

• 按版本号拆分独立的规范文件：每个版本对应单独的openapi-v1.yaml/openapi-v2.yaml，各文件独立定义对应版本的接口、请求响应参数、返回值，互不影响
• 公共定义复用：如果两个版本有大量重复的模型、参数规则，可以把公共部分抽成单独的components.yaml，在各版本文件里用$ref字段引用公共定义，减少重复代码
• Swagger UI多版本适配：如果用Swagger UI展示文档，在UI的初始化配置里传入多个版本的spec地址，即可通过下拉框切换不同版本的API文档，示例配置片段：

const ui = SwaggerUIBundle({
  urls: [
    {url: "openapi-v1.yaml", name: "v1 版本"},
    {url: "openapi-v2.yaml", name: "v2 版本"}
  ],
  "urls.primaryName": "v2 版本", // 默认展示最新版本
  dom_id: '#swagger-ui',
})

场景2：项目代码集成Swagger（以Java SpringBoot 生态为例） #

方案A：基于路径分组的多Docket配置 #

• 给不同版本的接口设置统一的路径前缀，比如v1版本接口前缀为/api/v1/**，v2版本前缀为/api/v2/**，同时接口代码按版本拆分不同包路径
• 配置多个Docket实例，每个实例对应一个版本，扫描对应路径下的接口，示例代码：

@Configuration
public class SwaggerConfig {
    // v1 版本Docket
    @Bean
    public Docket docketV1() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("v1 版本")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.api.v1"))
                .paths(PathSelectors.ant("/api/v1/**"))
                .build()
                .apiInfo(apiInfoV1());
    }

    // v2 版本Docket
    @Bean
    public Docket docketV2() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("v2 版本")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.api.v2"))
                .paths(PathSelectors.ant("/api/v2/**"))
                .build()
                .apiInfo(apiInfoV2());
    }
}

• 配置完成后启动项目，Swagger UI顶部会出现版本分组下拉框，切换即可查看对应版本的接口

方案B：基于注解标记版本 #

如果接口没有按路径拆分，可以自定义@ApiVersion注解给不同版本的接口方法打标记，Docket扫描时过滤带对应版本注解的接口即可，不需要拆分路径和包结构。

注意：迭代新版本时不要修改旧版本对应的接口代码和Swagger注解，避免旧版本文档被篡改。如果是同版本内的兼容升级，可以在文档里给旧方法加@Deprecated标记，新增方法直接放在同版本分组即可。

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