gin-swagger的安装使⽤（注释参数说明）
Swagger
Api框架
RestFul Api⽂档在线⾃动⽣成⼯具——>Api⽂档与API定义同步更新
直接运⾏，可以在线测试API接⼝
安装：
#1、安装swag
$ go get -u github/swaggo/swag/cmd/swag
#2、在go 项⽬中（包含）的⽬录，使⽤swag init命令⽣成相关⽂件。
$ swag init  #运⾏后发现在docs⽬录下出现 swagger.json  swagger.yaml 
#3、安装gin-swagger
$ go get -u github/swaggo/gin-swagger
$ go get -u github/swaggo/files
使⽤：
使⽤步骤见如下⽹址
注释参数
参考⽂档
常规API信息
注解描述例⼦
title**必需的。**应⽤程序的标题。// @title Swagger Example API
version**必需的。**提供应⽤程序API的版本。// @version 1.0
description应⽤程序的简短描述。// @description This is a sample server celler server. termsOfServic
e API的服务条款。// @termsOfService swagger.io/terms/ contact.name公开的API的联系信息。// @contact.name API Support
contact.url指向联系信息的URL。必须采⽤⽹址格式。// @ contact.url www.swagger.io/support
式。
// @ ail support@swagger.io
license.name**必需的。**⽤于API的许可证名称。// @ license.name Apache 2.0
license.url⽤于该API的许可证的URL。必须采⽤⽹址格式。// @ license.url /licenses/LICENSE-
2.0.html
host提供API的主机（名称或IP）。// @host localhost:8080 BasePath提供API的基本路径。// @BasePath / api / v1
安全
注解parameters example securitydefinitions.basic（基本认证）auth.// @securityDefinitions.basic BasicAuth securitydefinitions.apikey（密钥验证）auth.in, name// @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application（应⽤程
序⾝份验证）kenUrl, scope
//@securitydefinitions.oauth2.application
OAuth2Application
securitydefinitions.oauth2.implicit（隐式⾝份验
证）auth.authorizationUrl, scope
// @securitydefinitions.oauth2.implicit
OAuth2Implicit
securitydefinitions.oauth2.password（密码验
证）kenUrl, scope
// @securitydefinitions.oauth2.password
OAuth2Password
securitydefinitions.oauth2.accessCode（访问代
码认证auth.
tokenUrl, authorizationUrl,
scope
//@securitydefinitions.oauth2.accessCode
OAuth2AccessCode
注解parameters example
参数注释example
in// @in header
name// @name Authorization
tokenUrl// @tokenUrl example/oauth/token authorizationurl// @authorizationurl example/oauth/authorize scope.hoge// @scope.write Grants write access
API操作
注解描述
description操作⾏为的详细说明。
id⽤于标识操作的唯⼀字符串。在所有API操作中必须唯⼀。
tags每个API操作的标签列表，以逗号分隔。
summary该操作的简短摘要。
accept API可以使⽤的MIME类型的列表。值必须与“ 下所述相同。
produce API可以产⽣的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
Mime 类型注解
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 example/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。（注意：“默认”对于必需的参数没有意义。）请参阅/html/draft-fge-json-schema-validation-00#section-6.2。与JSON模式不同，此值必须符合为此参数定义的值。
maximum number See /html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum number See /html/draft-fge-json-schema-validation-00#section-5.1.3. maxLength integer See /html/draft-fge-json-schema-validation-00#section-5.2.1. minLength integer See /html/draft-fge-json-schema-validation-00#section-5.2.2.
enums[*]See /html/draft-fge-json-schema-validation-00#section-5.5.1.
栏位名称Type Description
Future
Field Name Type Description
format string前⾯提到的扩展格式。有关更多详细信息，请参见。
multipleOf number See /html/draft-fge-json-schema-validation-00#section-5.1.1.
pattern string See /html/draft-fge-json-schema-validation-00#section-5.2.3.
maxItems integer See /html/draft-fge-json-schema-validation-00#section-5.3.2.
minItems integer See /html/draft-fge-json-schema-validation-00#section-5.3.3.
param name
uniqueItems boolean See /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:"test/image/1.jpg,test/image/2.jpg"` }

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。