Go Swagger 文档如何标识必填字段？

go swagger 文档字段必填问题

有开发者反映，go 版的 swagger 在使用时遇到困难，遇到的具体问题是字段标注为必填，但查看文档时需要逐个点开才能确认。

必填字段标识

正常情况下，必填参数会在文档中显示一个红色星号（*）。

错误示例 (注释自动生成)

白瓜AI

白瓜AI，一个免费图文AI创作工具，支持 AI 仿写，图文生成，敏感词检测，图片去水印等等。

下载

type loginstructjson struct {
    userid         string `json:"user_id" valid:"required" structs:"user_id" binding:"required"` // 用户id
    regionid       string `json:"region_id" valid:"required" structs:"region_id"`                // 地区id        | 必填
    regionname     string `json:"region_name" valid:"required" structs:"region_name"`            // 地区名称        | 必填
    timezoneid     string `json:"timezone_id" valid:"required" structs:"timezone_id"`            // 时区id        | 必填
    timezonename   string `json:"timezone_name" valid:"required" structs:"timezone_name"`        // 时区名称        | 必填
    areaserverid   string `json:"area_server_id" valid:"required" structs:"area_server_id"`      // 区服id        | 必填
    areaservername string `json:"area_server_name" valid:"required" structs:"area_server_name"`  // 区服名称        | 必填
    channelid      string `json:"channel_id" valid:"required" structs:"channel_id"`              // 渠道id        | 必填
    channelname    string `json:"channel_name" valid:"required" structs:"channel_name"`          // 渠道名称        | 必填
    gameid         int    `json:"game_id" valid:"required" structs:"game_id"`                    // 游戏id         | 必填
    gamename       string `json:"game_name" structs:"game_name"`                                 // 游戏名称
    equipid        string `json:"equip_id" valid:"required" structs:"equip_id"`                  // 设备id          | 必填
    gameplatform   int    `json:"game_platform" valid:"min(0)" structs:"game_platform"`          // 平台类型         | 必填
    stoptime       int    `json:"stop_time" structs:"stop_time"`                                 // 停留时间      | 默认 0
}

正确示例 (手动编写)

必填参数后面会自带一个红色的`*`。

建议不使用注释自动生成

建议不要使用注释自动生成文档的方式，其缺点如下：

• 三方框架更新缓慢，无法支持最新的 openapi 标准。
• 注释代码量的实际并不减少。
• 会对源代码造成侵入。

推荐使用官方提供的 swagger editor 工具手动编写接口文档。