gin-swagger的安装使用（注释参数说明）

Swagger

• Api框架
• RestFul Api文档在线自动生成工具——>Api文档与API定义同步更新
• 直接运行，可以在线测试API接口

安装：

#1、安装swag
$ go get -u github.com/swaggo/swag/cmd/swag

#2、在go 项目中（包含main.go）的目录，使用swag init命令生成相关文件。
$ swag init  #运行后发现在docs目录下出现 swagger.json  swagger.yaml  docs.go

#3、安装gin-swagger
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

使用：

使用步骤见如下网址
官方参考文档

注释参数

参考文档

https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html

常规API信息

注解	描述	例子
title	**必需的。**应用程序的标题。	// @title Swagger Example API
version	**必需的。**提供应用程序API的版本。	// @version 1.0
description	应用程序的简短描述。	// @description This is a sample server celler server.
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 [email protected]
license.name	**必需的。**用于API的许可证名称。	// @ license.name Apache 2.0
license.url	用于该API的许可证的URL。必须采用网址格式。	// @ license.url http://www.apache.org/licenses/LICENSE-2.0.html
host	提供API的主机（名称或IP）。	// @host localhost:8080
BasePath	提供API的基本路径。	// @BasePath / api / v1

安全

注解		parameters	example
securitydefinitions.basic（基本认证）	Basic auth.		// @securityDefinitions.basic BasicAuth
securitydefinitions.apikey（密钥验证）	API key auth.	in, name	// @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application（应用程序身份验证）	OAuth2 application auth.	tokenUrl, scope	//@securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit（隐式身份验证）	OAuth2 implicit auth.	authorizationUrl, scope	// @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password（密码验证）	OAuth2 password auth.	tokenUrl, scope	// @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode（访问代码认证	OAuth2 access code auth.	tokenUrl, authorizationUrl, scope	//@securitydefinitions.oauth2.accessCode OAuth2AccessCode

参数注释	example
in	// @in header
name	// @name Authorization
tokenUrl	// @tokenUrl https://example.com/oauth/token
authorizationurl	// @authorizationurl https://example.com/oauth/authorize
scope.hoge	// @scope.write Grants write access

API操作

注解	描述
description	操作行为的详细说明。
id	用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags	每个API操作的标签列表，以逗号分隔。
summary	该操作的简短摘要。
accept	API可以使用的MIME类型的列表。值必须与“ Mime类型”下所述相同。
produce	API可以产生的MIME类型的列表。值必须与“ Mime类型”下所述相同。
param	用空格分隔的参数。param name，param type，data type，is mandatory?，comment attribute(optional)
security	每个API操作的安全性。
success	成功响应之间用空格隔开。return code，{param type}，data type，comment
failure	由空格分隔的故障响应。return code，{param type}，data type，comment
router	由空格分隔的故障响应。path，[httpMethod]

Mime Types

Mime 类型	注解
application/json	application/json, json
text/xml	text/xml, xml
text/plain	text/plain, plain
html	text/html, html
multipart/form-data	multipart/form-data, mpfd
application/x-www-form-urlencoded	application/x-www-form-urlencoded, x-www-form-urlencoded
application/vnd.api+json	application/vnd.api+json, json-api
application/x-json-stream	application/x-json-stream, json-stream
application/octet-stream	application/octet-stream, octet-stream
image/png	image/png, png
image/jpeg	image/jpeg, jpeg
image/gif	image/gif, gif

安全Security

常规API信息

// @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

每个API操作

// @Security ApiKeyAuth

Make it AND condition

// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]

参数类型Param Type

• object (struct)
• string (string)
• integer (int, uint, uint32, uint64)
• number (float32)
• boolean (bool)
• array

数据类型Data Type

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

属性Attribute

// @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" mininum(1) maxinum(10)
// @Param default query string false "string default" default(A)

Available

栏位名称	Type	Description
default	*	声明如果未提供任何参数，则服务器将使用的参数值，例如，如果请求中的客户端未提供该参数，则用于控制每页结果数的“计数”可能默认为100。（注意：“默认”对于必需的参数没有意义。）请参阅https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。与JSON模式不同，此值必须符合type为此参数定义的值。
maximum	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
maxLength	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums	[*]	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.

Future

Field Name	Type	Description
format	string	前面提到的扩展格式type。有关更多详细信息，请参见数据类型格式。
multipleOf	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
pattern	string	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
maxItems	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
minItems	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
uniqueItems	boolean	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.
collectionFormat	string	确定数组的格式（如果使用类型数组）。可能的值为：（如下）

• csv-逗号分隔的值foo，bar。
• ssv-空格分隔的值foo bar。
• tsv-制表符分隔值foo \ tbar。
• pipes-管道分隔值foo|bar。
• “ multi”-对应多个参数实例，而不是单个实例foo = bar＆foo = baz的多个值。这仅对参数[in]（＃parameterIn）“ query”或“ formData”有效。

默认值为csv

用户定义的具有数组类型的结构

// @Success 200 {array} model.Account <-- This is a user defined struct.
package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}

使用多路径参数

/// ...
// @Param group_id path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

struct的示例值

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"`
}