如何使用Go-Swagger在单路由文件中为版本化API生成Swagger规范？

要让go-swagger为v1、v2版本的API生成不同的规范文件，核心是通过唯一operation ID+版本标签区分不同版本的API，再通过命令行参数过滤生成对应版本的文档。具体步骤如下：

1. 修正路由上的Swagger注解 #

首先给每个版本的API设置唯一的operation ID，并添加版本专属标签（如v1、v2），避免ID冲突导致解析错误：

r := chi.NewRouter()

// swagger:operation POST /v1/resource add-resource-v1
// ---
// tags:
// - v1
// summary: 添加资源详情（v1版本）
// responses:
//   200:
//     description: 资源添加成功
//     schema:
//       $ref: "#/definitions/ResourceRespV1"
r.Post("/v1/resource", resourceHandler.AddResourceDetails)

// swagger:operation POST /v2/resource add-resource-v2
// ---
// tags:
// - v2
// summary: 添加资源详情（v2版本）
// responses:
//   200:
//     description: 资源添加成功
//     schema:
//       $ref: "#/definitions/ResourceRespV2"
r.Post("/v2/resource", resourceHandler.AddResourceDetails)

2. 为不同版本定义独立的参数/响应结构体 #

如果v1和v2的请求体、响应体结构不同，要为每个版本单独定义结构体，并通过operation ID关联：

// swagger:parameters add-resource-v1
type AddResourceParamsV1 struct {
    // 请求体参数
    // in: body
    Body ResourceV1 `json:"body"`
}

// swagger:parameters add-resource-v2
type AddResourceParamsV2 struct {
    // 请求体参数
    // in: body
    Body ResourceV2 `json:"body"`
}

// swagger:definition ResourceV1
type ResourceV1 struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

// swagger:definition ResourceV2
type ResourceV2 struct {
    ID        string `json:"id"`
    Name      string `json:"name"`
    Timestamp int64  `json:"timestamp"` // v2新增字段
}

// swagger:definition ResourceRespV1
type ResourceRespV1 struct {
    Code int    `json:"code"`
    Msg  string `json:"msg"`
}

// swagger:definition ResourceRespV2
type ResourceRespV2 struct {
    Code int         `json:"code"`
    Msg  string      `json:"msg"`
    Data *ResourceV2 `json:"data"` // v2新增返回数据
}

3. 分版本生成Swagger规范文件 #

使用swagger generate spec命令，通过--tags参数过滤对应版本的API，生成独立的规范文件：

• 生成v1版本的Swagger文档：

swagger generate spec --tags v1 -o swagger-v1.json

• 生成v2版本的Swagger文档：

swagger generate spec --tags v2 -o swagger-v2.json

注意事项 #

• 每个swagger:operation的ID必须唯一，不能重复（你之前的代码里两个API用了同一个AddResourceDetailsID，这会导致go-swagger无法区分）。
• 如果v1和v2的handler逻辑完全一致，但请求/响应结构不同，必须通过独立的结构体注解来区分。
• 确保安装最新版的go-swagger，避免旧版本的兼容性问题。

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