swag注解指南(gin 使用swagger生成文档)

如果想要为gin 配置swagger ,会需要用到这样一个库swag,具体怎么配置我就不在这篇写了。

这篇主要讲注解怎么写。配置好框架之后,你会需要写一堆注解,好让swag知道怎么生成文档.

由于官方的例子比较凌乱,对于没接触过的人,我觉得会造成一些困扰。所以特意整理一下,发出来。希望能帮助到需要的人。

API 操作

注解 描述
description 描述,操作行为的详细解释
id ID,用于识别操作的唯一字符串。在所有API操作中必须是唯一的。
tags 标签,A list of tags to each API operation that separated by commas.
summary 概要,A short summary of what the operation does.
accept API可以使用的MIME类型列表。值必须如MIME类型所述。
produce API可以生成的MIME类型列表。值必须如MIME类型所述。
param 参数, 以空格分隔的参数 param name,param type,data type,is mandatory?,comment attribute(optional)
security 安全性
success 以空格分隔的成功响应。 return code,{param type},data type,comment
failure 以空格分隔的失败响应。 return code,{param type},data type,comment
router 访问路径。 path,[httpMethod]

例子

celler/controller

局限性

  • 不支持跨包装模型。只在项目根文件夹中搜索。 见 #39

Mime 类型

1
2
3
4
5
6
7
8
9
10
11
12
json
application/json
xml
text/xml
plain
text/plain
html
text/html
mpfd
multipart/form-data
json-api
application/vnd.api+json

安全

一般API信息

1
2
3
4
5
6
// @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操作

1
// @Security ApiKeyAuth

创建和条件

1
2
// @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

属性

1
2
3
4
5
6
// @Param enumstring查询字符串false“字符串枚举”枚举(A,B,C)
// @Param enumint查询int int“int enums”枚举(1,2,3)
// @Param枚举查询编号false“int枚举“枚举(1.1,1.2,1.3)
// @Param字符串查询字符串假”字符串有效“minlength(5)maxlength(10)
// @Param int查询int假”int valid“mininum(1)maxinum(10)
// @Param默认查询字符串false“字符串默认”默认(A)

可以得到

字段名 类型 描述
default * Declares the value of the parameter that the server will use if none is provided, for example a “count” to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: “default” has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined type for this parameter.
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.

功能

字段名 类型 描述
format string The extending format for the previously mentioned type. See Data Type Formats for further details.
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 Determines the format of the array if type array is used. Possible values are:
  • csv - comma separated values foo,bar.
  • ssv - space separated values foo bar.
  • tsv - tab separated values foo\tbar.
  • pipes - pipe separated values foo|bar.
  • multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in “query” or “formData”.
Default value is csv.

提示

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

1
// @Success 200 {array} model.Account <-- This is a user defined struct.
1
2
3
4
5
6
package model
type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
}

使用多个路径参数

1
2
3
4
5
/// ...
// @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]

结构体的例子

1
2
3
4
5
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"`
}
坚持原创技术分享,您的支持将鼓励我继续创作!