如何为Go中Protobuf生成的结构体添加example标签适配Swaggo文档？

以下是几个针对Swaggo无法为Protobuf生成结构体添加example标签的可行方案：

方案1：直接在API注释中使用@Example注解 #

不用修改任何结构体，直接在接口的Swaggo注释里通过@Example指定请求/响应的JSON示例，Swaggo会直接渲染这个示例到文档中。

示例代码：

// @Summary 创建用户
// @Produce json
// @Param user body User true "创建用户的请求体"
// @Example { "name": "John" }
// @Success 200 {object} User
// @Router /users [post]
func createUserHandler(c *gin.Context) {
    // 业务逻辑实现
}

方案2：创建自定义Swaggo专用结构体 #

定义一个和Protobuf结构体字段完全匹配的自定义结构体，给它加上example标签，在Swaggo注释中使用这个自定义结构体，实际业务代码里再将其转换为Protobuf结构体。

示例代码：

// 仅用于Swaggo文档的自定义结构体
type SwagUser struct {
    Name string `json:"name" example:"John"`
}

// API接口注释使用SwagUser
// @Summary 获取用户详情
// @Produce json
// @Param user_id path string true "用户ID"
// @Success 200 {object} SwagUser "用户信息"
// @Router /users/{user_id} [get]
func getUserHandler(c *gin.Context) {
    // 从数据库或其他服务获取Protobuf格式的User
    protoUser := &User{Name: "John"}
    // 转换为SwagUser返回（或直接返回protoUser，Swaggo文档用SwagUser展示示例）
    c.JSON(http.StatusOK, protoUser)
}

方案3：通过Protobuf自定义选项注入示例 #

在Protobuf文件中定义自定义字段选项来指定示例值，然后通过Swaggo的扩展机制读取这些选项生成文档示例。

1. 首先在Protobuf文件中定义自定义选项：

import "google/protobuf/descriptor.proto";

// 定义自定义字段选项，编号需在50000-99999范围内（Protobuf预留的自定义编号段）
extend google.protobuf.FieldOptions {
    optional string example = 50000;
}

message User {
    string name = 1 [(example) = "John"];
}

2. 生成Go代码后，编写Swaggo的自定义分析器（或借助第三方扩展），读取Protobuf结构体字段的元数据，提取example选项值并注入到Swaggo文档中。这个方式适合需要统一维护Protobuf和API文档示例的场景，但需要对Swaggo的源码有一定了解。

方案4：使用@Schema注解手动指定示例 #

部分Swaggo版本支持通过@Schema注解直接为结构体字段指定示例，无需修改结构体标签。

示例代码：

// @Summary 更新用户信息
// @Produce json
// @Param user body User true "更新用户的请求体"
// @Schema(example={"name": "John"})
// @Success 200 {object} User
// @Router /users/{user_id} [put]
func updateUserHandler(c *gin.Context) {
    // 业务逻辑实现
}

内容的提问来源于stack exchange，提问作者Li-Khan