Swagger接口文檔

Swagger接口文檔
1.安裝 swag

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

2.驗證是否安裝成功

$ swag -v

3.編寫API注釋
以官網文檔為范例

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string    "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]
func xxx() {
}

4.運行生成docs文檔

 swag init

5.在根目錄下會生成如下目錄結構

docs/
├── docs.go
└── swagger
    ├── swagger.json
└── swagger.yaml

6.main.go中添加API注釋

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [e-mail]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func main() {
	e := echo.New()

	e.GET("/swagger/*", echoSwagger.WrapHandler)

	e.Logger.Fatal(e.Start(":1323"))
}

字段說明

注釋	說明	示例
title	必填	應用程序的名稱。
version	必填 提供應用程序API的版本。	// @version 1.0
description	應用程序的簡短描述。	// @description This is a sample server celler server.
tag.name	標簽的名稱。	// @tag.name This is the name of the tag
tag.description	標簽的描述。	// @tag.description Cool Description
tag.docs.url	標簽的外部文檔的URL。	// @tag.docs.url https://example.com
tag.docs.description	標簽的外部文檔說明。	// @tag.docs.description Best example documentation
termsOfService	API的服務條款。	// @termsOfService http://swagger.io/terms/
contact.name	公開的API的聯系信息。	// @contact.name API Support
contact.url	聯系信息的URL。 必須采用網址格式。	// @contact.url http://www.swagger.io/support
contact.email	聯系人/組織的電子郵件地址。 必須采用電子郵件地址的格式。	// @contact.email [e-mail]
license.name	必填 用於API的許可證名稱。	// @license.name Apache 2.0
license.url	用於API的許可證的URL。 必須采用網址格式。	// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
BasePath	運行API的基本路徑。	// @BasePath /api/v1

7.controller代碼中添加API操作注釋

// ShowAccount godoc
// @Summary Show a account
// @Description get string by ID
// @ID get-string-by-int
// @Accept  json
// @Produce  json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Header 200 {string} Token "qwerty"
// @Failure 400,404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Failure default {object} httputil.DefaultError
// @Router /accounts/{id} [get]

字段說明

注釋	描述
description	操作行為的詳細說明。
description.markdown	應用程序的簡短描述。該描述將從名為endpointname.md的文件中讀取。
id	用於標識操作的唯一字符串。在所有API操作中必須唯一。
tags	每個API操作的標簽列表，以逗號分隔。
summary	該操作的簡短摘要。
accept	API可以使用的MIME類型的列表。值必須如“Mime類型”中所述。
produce	API可以生成的MIME類型的列表。值必須如“Mime類型”中所述。
param	用空格分隔的參數。param name,param type,data type,is mandatory?,
security	每個API操作的安全性。
success	以空格分隔的成功響應。return code,{param type},data type,comment
failure	以空格分隔的故障響應。return code,{param type},data type,comment
response	與success、failure作用相同
header	以空格分隔的頭字段。 return code,{param type},data type,comment
router	以空格分隔的路徑定義。 path,[httpMethod]
x-name	擴展字段必須以x-開頭，並且只能使用json值。

參數類型

query
path
header
body
formData

數據類型

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

屬性

// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" minimum(1) maximum(10)
// @Param default query string false "string default" default(A)
// @Param collection query []string false "string collection" collectionFormat(multi)

結構體的示例值

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
    PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
}

Swag幫助文檔:

https://github.com/swaggo/swag/blob/master/README_zh-CN.md
Echo swagger: https://github.com/swaggo/echo-swagger
Swagger格式：https://razeencheng.com/post/go-swagger