Golang Swag @Param annotation格式

Go的swagger套件swaggo/swag的@Param用法如下。

範例環境：

• Go 1.19
• swaggo/swag v1.16

事前要求

參考「Golang Gin 使用gin-swagger產生Swagger REST API文件」產生Swagger API文件。

@Param annotation

在API前加上@Param可設定API的輸入參數，格式為以下用空白分隔的屬性：
param name,param type,data type,is mandatory,comment attribute(optional)
個欄位說明如下：

• param name - 參數名稱
• param type - 參數類型，包含以下：
  • header - 請求頭
  • path - path variable，即/hello/{id}url的{id}部分。
  • query - query string，即/hello?name=johnurl問號後面的name=john部分。
  • body - request body，通常為JSON格式。
  • formData - 表單資料。
• data type - 參數資料型態，接受以下：
  • string - 字串
  • integer - 整數
  • number - 浮點數
  • boolean - 布林值
  • file - 上傳檔案
  • user defined struct - 使用者自訂struct
• is mandatory - 是否必填，true or false。
• comment - 參數說明，使用雙引號"包夾內容。
• attribute - 參數屬性，選填，依序往後增加可有多個。可用屬性參考Available。例如：
  • enums - 列舉值
  • example - 參數範例

例如下面在API/demo/v1/hello加了以下四個param。

// @Success 200 {string} string
// @Router /demo/v1/hello [get]
// @Param Authorization header string true "JWT token" default(Bearer)
// @Param id path string true "ID"
// @Param payload body HelloRequest true "Hello request"
// @Param age query string false "Age"
func hello(c *gin.Context) {
    c.JSON(200, "Hello - v1")
}

type HelloRequest struct {
    Name  string `json:"name" binding:"required"`
    Email string `json:"email"`
}

github

測試

輸入swag init刷新swagger docs後，啟動應用程式在Swagger頁面顯示如下。