Swagger

Descriptiontag.docs.url标签的外部文档的URL。

//

tag.docs.urlhttps://example.comtag.docs.description标签的外部文档说明。

//

tag.docs.description

documentationtermsOfServiceAPI的服务条款。

//

termsOfServicehttp://swagger.io/terms/contact.name公开的API的联系信息。

//

contact.name

contact.urlhttp://www.swagger.io/supportcontact.email联系人/组织的电子邮件地址。

contact.emailsupportswagger.iolicense.name必填

license.name

license.urlhttp://www.apache.org/licenses/LICENSE-2.0.htmlhost运行API的主机主机名或IP地址。

//

host

localhost:8080BasePath运行API的基本路径。

//

BasePath

jsonproduceAPI可以生成的MIME类型的列表。

值必须如“Mime类型”中所述。

//

produce

jsonquery.collection.format请求URI

query里数组参数的默认格式csvmultipipestsvssv。

schemes

httpsexternalDocs.descriptionDescription

***

externalDocs.urlhttps://swagger.io/resources/open-api/x-name扩展的键必须以x-开头并且只能使用json值//

x-example-key

这部分注释用于声明一个接口可将这部分注释添加到相应的接口方法上。

注释描述description操作行为的详细说明。

description.markdown应用程序的简短描述。

该描述将从名为endpointname.md的文件中读取。

id用于标识操作的唯一字符串。

在所有API操作中必须唯一。

tags每个API操作的标签列表以逗号分隔。

summary该操作的简短摘要。

acceptAPI

MIME

值必须如“Mime类型”中所述。

produceAPI可以生成的MIME类型的列表。

值必须如“Mime类型”中所述。

param用空格分隔的参数。

param

name,param

attribute(optional)security每个API操作的安全性。

success以空格分隔的成功响应。

return

code,{param

type,commentfailure以空格分隔的故障响应。

return

code,{param

type,commentresponse与success、failure作用相同header以空格分隔的头字段。

return

code,{param

type,commentrouter以空格分隔的路径定义。

path,[httpMethod]deprecatedrouter与router相同但是是deprecated的。

x-name扩展字段必须以x-开头并且只能使用json值。

deprecated将当前API操作的所有路径设置为deprecated

1.3

Typejsonapplication/jsonxmltext/xmlplaintext/plainhtmltext/htmlmpfdmultipart/form-datax-www-form-urlencodedapplication/x-www-form-urlencodedjson-apiapplication/vnd.apijsonjson-streamapplication/x-json-streamoctet-streamapplication/octet-streampngimage/pngjpegimage/jpeggifimage/gif

参数类型枚举

中的参数formDatax-www-form-urlencoded

数据类型枚举

数据类型对应实际类型stringstringintegerint,

uint,

uint64numberfloat32booleanbool结构体结构体类型

更多用法内容可参考官方文档https://github.com/swaggo/swag/blob/master/README_zh-CN.md

1.4

github.com/swaggo/swag/cmd/swaglatest使用命令生成

swag

ginSwagger.WrapHandler(swaggerFiles.Handler))通过

/swagger/index.html

我们一个系统可能包含开发者、用户、管理员多种角色我们需要为不同的角色分别创建接口文档。

4.1

[arguments...]OPTIONS:--generalInfo

value,

API通用信息所在的go源文件路径如果是相对路径则基于API解析

(默认:

是否解析vendor中的go源文件默认不--markdownFiles

value,

指定API的描述信息所使用的markdown文件所在的目录--generatedTime

是否输出时间到输出文件docs.go的顶部默认是--codeExampleFiles

value,

扩展的代码示例文件的文件夹默认禁用--parseInternal

internal

internal/application/paramAdmin

接口所在为

internal/application/router/api/content。

Admin

internal/application/router/api/admin,internal/application/param

./docs/admin

internal/application/router/api/content,internal/application/param

./docs/content

ginSwagger.WrapHandler(swaggerFiles.NewHandler(),

func(config

swaggerGroup.GET(/content/*any,

ginSwagger.WrapHandler(swaggerFiles.NewHandler(),

func(config