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 support@swagger.io

// @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 support@swagger.io
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