網頁

2023/7/6

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。例如:

例如下面在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頁面顯示如下。



沒有留言:

張貼留言