swagger 注释说明

一、接口注释核心字段

在 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"`
    // 邮箱（示例值：[e-mail]）
    Email string `json:"email" example:"[e-mail]"`
}

// 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 ...。

---

六、最佳实践

1. 统一标签命名：如 @Tags users 用于所有用户相关接口。
2. 详细描述参数：在 @Param 中明确参数是否必填（true/false）。
3. 分离模型定义：将请求/响应模型放在独立的 models 包中，提升可维护性。
4. 版本控制：在全局注解中指定 @BasePath /api/v1，便于区分 API 版本。