一、接口注釋核心字段
在 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 版本。
)
