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信息

// @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]

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

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

• 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]

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