go學習-使用swagger生成接口文檔

1安裝 swag 命令

go get -u github.com/swaggo/swag/cmd/swag

2編寫注解

服務基礎信息（main.go)

// @title swagger使用例子
// @version 1.0
// @description swagger 入門使用例子
// @host localhost:8080 --->這里寫接口服務的host
// @BasePath /api/vi -->這里寫base path

api信息(controller中各個接口前)

// @summary 接口簡介
// @Description 接口描述
// @Accept json --> 可生成的MIME類型，既接收類型
// @Produce json --> 可生成的MIME類型，既響應返回類型
// @Param user body domain.UserStruct "傳入參數是struct"
// Success 200 {object} Response --> 成功后返回數據結構
// Failure 400 {object} ResponseError --> 失敗后返回數據結構
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @Router /check [get] --> 路由地址及請求方法

API 注釋定義

• param 參數 格式: [ 參數名稱 參數類型 數據類型 是否必須 備注 限制屬性 ] 空格分割
  @Params userId query string true "用戶id" minlength(3) maxlength(100)
  @Params status query integer false "狀態：0 1" Enums(0, 1) defualt(0)

參數可用類型 [param type]

query :表示帶在 url 之后的參數 get請求
path :path 表示請求路徑上得參數 /check{id} 例：@Params id path integer false
header :表示帶在 header 信息中得參數
body :表示是一個 raw 數據請求 post請求
formDate:formData 表示是 post 請求的數據

數據可用類型 [data type]

string(string)
integer(int, uint, uint32, uint64)
boolean(bool)
user defined struct

可配置屬性

defualt * 參數默認值
maximum number 最大值
mininum number 最小值
maxLength integer 最大長度
minLength integer 最小長度
enums [*] 枚舉類型
format string
collectionFormat string query數組分割模式

• security 安全性

success 成功響應 格式: [ 狀態碼 {數據類型} 數據類型 備注 ]

@Success 200 {object} Response "返回空對象"

failure 失敗響應 格式: [ 狀態碼 {數據類型} 數據類型 備注 ]

@Failure 400 {object} ResponseError

• header 請求頭字段 格式: [ 狀態碼 {數據類型} 數據類型 備注 ]

// @Header 200 {string} Token "qwerty"

• router 路由路徑

// @Router /user/{userId} [get]

3生成文檔

// 根目錄執行
swag init
執行后會生成docs的文件夾
./docs
├── docs.go
├── swagger.json
└── swagger.yaml

4配置文檔路由

在配置路由的文件中添加

import (
     _ "server/docs"  // 這里需要引入本地已生成文檔
     ginSwagger "github.com/swaggo/gin-swagger" 
     swaggerFiles "github.com/swaggo/files"
)


func main(){
    ...
    
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

5啟動服務並訪問

go run main.go
// 當前文檔路徑: http://localhost:8080/swagger/index.html

6每次更新注釋后記得 swag init 更新json文件