一、接口注释核心字段
在 Go 的路由处理函数（Handler）上方添加注释，支持以下常用注解：
| 注解名称 | 用途说明 | 示例格式 |
|---|---|---|
@Summary | 接口简要描述 | @Summary 创建用户 |
@Description | 接口详细说明 | @Description 通过用户名和邮箱创建新用户 |
@Tags | 接口分组标签（用于在 Swagger UI 中分类） | @Tags users |
@Accept | 接口接受的请求格式（如 json, xml, form-data） | @Accept json |
@Produce | 接口返回的响应格式（如 json, xml） | @Produce json |
@Param | 定义请求参数（路径参数、查询参数、请求体等） | @Param id path int true "用户ID" |
@Success | 成功响应的状态码、数据结构及描述 | @Success 200 {object} User |
@Failure | 失败响应的状态码、数据结构及描述 | @Failure 404 {object} ErrorResponse |
@Router | 定义接口路由路径和 HTTP 方法 | @Router /users/{id} [get] |
@Security | 接口使用的安全策略（需先在全局定义 @securityDefinitions） | @Security ApiKeyAuth |
二、@Param 参数详解
语法格式
@Param 参数名 参数位置 数据类型 是否必填 "描述"
参数位置
path：URL 路径参数（如/users/{id}）query：URL 查询参数（如/users?name=John）header：HTTP 头参数body：请求体（通常用于 POST/PUT）formData：表单数据（如文件上传）
数据类型
- 基本类型：
int,string,boolean等 - 模型对象：
{object} User（需在代码中定义User结构体）
示例
// 路径参数
// @Param id path int true "用户ID"// 查询参数
// @Param name query string false "用户名"// 请求体（JSON）
// @Param user body User true "用户信息"// 表单文件上传
// @Param file formData file true "上传文件"
三、完整接口注释示例
示例 1：GET 请求（带路径参数）
// GetUser 获取用户详情
// @Summary 通过用户ID获取详情
// @Description 根据ID查询用户信息
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} User
// @Failure 404 {object} ErrorResponse
// @Router /users/{id} [get]
func GetUser(c *gin.Context) { ... }
示例 2：POST 请求（带请求体）
// CreateUser 创建用户
// @Summary 创建新用户
// @Description 通过JSON数据创建用户
// @Tags users
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 201 {object} User
// @Failure 400 {object} ErrorResponse
// @Router /users [post]
func CreateUser(c *gin.Context) { ... }
示例 3：文件上传（表单）
// UploadFile 上传文件
// @Summary 上传文件
// @Description 通过表单上传文件
// @Tags files
// @Accept multipart/form-data
// @Produce json
// @Param file formData file true "上传文件"
// @Success 200 {object} SuccessResponse
// @Router /upload [post]
func UploadFile(c *gin.Context) { ... }
四、模型定义注释
在结构体（请求/响应模型）上添加注释，Swagger 会自动解析字段：
// User 用户信息模型
type User struct {// 用户ID（示例值：1）ID int `json:"id" example:"1"`// 用户名（示例值：John）Name string `json:"name" example:"John"`// 邮箱（示例值：john@example.com）Email string `json:"email" example:"john@example.com"`
}// ErrorResponse 错误响应模型
type ErrorResponse struct {// 错误码（示例值：404）Code int `json:"code" example:"404"`// 错误信息（示例值："用户不存在"）Message string `json:"message" example:"用户不存在"`
}
五、常见问题
1. 文档未生成或未更新
- 解决：确保运行
swag init -g main.go并重新编译代码。 - 检查：注释必须紧贴在路由处理函数上方，不能有空行。
2. 模型字段未显示
- 解决：确保结构体字段有
json标签，例如json:"id"。 - 示例值：使用
example:"1"标签为字段添加示例值。
3. 参数绑定失败
- 检查：
@Param注解中的参数位置（如path/query）与实际代码是否一致。 - 示例：代码中使用
c.Param("id")时，Swagger 注解应为@Param id path ...。
六、最佳实践
- 统一标签命名：如
@Tags users用于所有用户相关接口。 - 详细描述参数：在
@Param中明确参数是否必填（true/false）。 - 分离模型定义：将请求/响应模型放在独立的
models包中，提升可维护性。 - 版本控制：在全局注解中指定
@BasePath /api/v1，便于区分 API 版本。
)
