Go语言swag如何注释_Go语言文档自动生成【规范】-Golang-PHP中文网

swag文档生成需严格遵循语法和位置规则：注释必须紧贴首字母大写的具名handler函数、无空行，且含@summary和@router；结构体字段须有json:"xxx" tag；全局注释如@title须置于main包文件顶部连续块中。

go语言swag如何注释_go语言文档自动生成【规范】

swag 注释不是随便写几行注释就能生成文档的，它有一套硬性语法和位置规则，漏掉 @Summary 或 @Router，接口就直接消失；结构体字段没 json: tag，字段就为空。

注释必须紧贴 handler 函数，且不能有空行

swag 只扫描「具名函数」上方连续、无空行的 // @ 注释块。写在闭包、匿名函数、func main() 里，或者中间插一行空注释，整个函数就被跳过。

@Summary 和 @Router 是强制项，缺一不可；@Summary 必须是注释块第一行
注释块内不能混用 /* */，只认 // 行注释
函数名必须首字母大写（可导出），否则 swag 当作私有函数忽略
示例正确写法：

// @Summary 获取用户详情
// @Description 根据 ID 查询单个用户
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} models.User
// @Failure 404 {object} models.ErrorResponse
// @Router /api/v1/users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

`@Param` 类型必须和参数实际来源一致

Gin 不会把 query 参数自动映射成 path，swag 也不会猜——你写错 path 却传的是 query，文档里参数就挂错位置，前端“Try it out”填了也调不通。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本官方下载，版本号 1.26.0，适合旧项目维护、兼容性测试和指定版本开发环境搭建。

下载

path：对应 URL 路径变量，如 /users/{id} 中的 id，类型写 int 或 string（按 handler 里 c.Param("id") 实际转的类型）
query：对应 URL 查询参数，如 ?page=1&limit=10，类型写 int、string 等原始类型
body：仅用于 POST/PUT，必须配 @Success 200 {object} YourStruct，且结构体字段要有 json: tag
别写 @Param data body interface{}——swag 解析不出字段，响应模型会是空 {}

结构体字段不显示？大概率缺 `json:` tag 或未导出

swag 不反射字段，也不读字段名，它只认 json: tag 的键名。字段名是 UserName，但 tag 是 json:"user_name"，文档里就显示 user_name；没 tag 就不出现，哪怕字段是导出的。

所有要出现在文档里的字段，都得是首字母大写 + json:"xxx"
time.Time 字段建议加 time_format:"2006-01-02T15:04:05Z"，否则可能渲染成 Unix 时间戳数字
嵌套结构体（如 User.Address *Address）要求 Address 类型本身也有 json: tag，且被当前文件 import
别用 map[string]interface{} 或 interface{} 作响应体——改用明确结构体，或 struct{ Data interface{} } + @Schema 注释说明

`swag init` 找不到 `@title`？检查注释位置和模块路径

报错 failed to parse general API info，90% 是因为 // @title 这类全局注释没写对地方：它必须在 main 包的某个 .go 文件顶部，且连续无空行，也不能被其他代码或注释隔开。

如果项目结构是 cmd/myapp/main.go，执行 swag init -g cmd/myapp/main.go，别只在根目录跑默认命令
确保 main.go 在 package main 下，且 // @title 块前面没有其他 Go 代码（包括 import）
跨 module 引用结构体（如 models.User）时，必须加 // @modelsPackage github.com/yourname/project/models
字段用 snake_case（如 user_name string `json:"user_name"`）时，加 -p snakecase 参数，否则字段名解析失败