GO 的 Web 开发系列（五）—— 使用 Swagger 生成一份好看的接口文档

经过前面的文章，已经完成了 Web 系统基础功能的搭建，也实现了 API 接口、HTML 模板渲染等功能。接下来要做的就是使用 Swagger 工具，为这些 Api 接口生成一份好看的接口文档。

一、写注释

注释是 Swagger 的灵魂，Swagger 是通过特定格式的注释生成接口文档的。

1.1 基础注释

这部分基础注释对全接口文档通用，指定接口文档的基础信息，可添加在 main 函数上。

注释	说明	示例
title	必填应用程序的名称。	// @title Swagger Example API
version	必填提供应用程序API的版本。	// @version 1.0
description	应用程序的简短描述。	// @description This is a sample server celler server.
tag.name	标签的名称。	// @tag.name This is the name of the tag
tag.description	标签的描述。	// @tag.description Cool Description
tag.docs.url	标签的外部文档的URL。	// @tag.docs.urlhttps://example.com
tag.docs.description	标签的外部文档说明。	// @tag.docs.description Best example documentation
termsOfService	API的服务条款。	// @termsOfServicehttp://swagger.io/terms/
contact.name	公开的API的联系信息。	// @contact.name API Support
contact.url	联系信息的URL。必须采用网址格式。	// @contact.urlhttp://www.swagger.io/support
contact.email	联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。	// @contact.emailsupport@swagger.io
license.name	必填用于API的许可证名称。	// @license.name Apache 2.0
license.url	用于API的许可证的URL。必须采用网址格式。	// @license.urlhttp://www.apache.org/licenses/LICENSE-2.0.html
host	运行API的主机（主机名或IP地址）。	// @host localhost:8080
BasePath	运行API的基本路径。	// @BasePath /api/v1
accept	API 可以使用的 MIME 类型列表。请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。值必须如"Mime类型"中所述。	// @accept json
produce	API可以生成的MIME类型的列表。值必须如"Mime类型"中所述。	// @produce json
query.collection.format	请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。如果未设置，则默认为csv。	// @query.collection.format multi
schemes	用空格分隔的请求的传输协议。	// @schemes http https
externalDocs.description	Description of the external document.	// @externalDocs.description OpenAPI
externalDocs.url	URL of the external document.	// @externalDocs.urlhttps://swagger.io/resources/open-api/
x-name	扩展的键必须以x-开头，并且只能使用json值	// @x-example-key {"key": "value"}

1.2 API 接口注释

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

注释	描述
description	操作行为的详细说明。
description.markdown	应用程序的简短描述。该描述将从名为`endpointname.md`的文件中读取。
id	用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags	每个API操作的标签列表，以逗号分隔。
summary	该操作的简短摘要。
accept	API 可以使用的 MIME 类型列表。请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。值必须如"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`
response	与success、failure作用相同
header	以空格分隔的头字段。`return code`,`{param type}`,`data type`,`comment`
router	以空格分隔的路径定义。`path`,`[httpMethod]`
deprecatedrouter	与router相同，但是是deprecated的。
x-name	扩展字段必须以`x-`开头，并且只能使用json值。
deprecated	将当前API操作的所有路径设置为deprecated

1.3 类型枚举

以上接口注解中用到的枚举类型的介绍。

Mime 类型枚举：

swag 接受所有格式正确的 MIME 类型, 即使匹配 */*。除此之外，swag 还接受某些 MIME 类型的别名。

Alias	MIME Type
json	application/json
xml	text/xml
plain	text/plain
html	text/html
mpfd	multipart/form-data
x-www-form-urlencoded	application/x-www-form-urlencoded
json-api	application/vnd.api+json
json-stream	application/x-json-stream
octet-stream	application/octet-stream
png	image/png
jpeg	image/jpeg
gif	image/gif

参数类型枚举：

参数类型	描述
query	请求的 url 参数
path	放在请求路径中的参数
header	请求 header 中的参数
body	请求 body 中的参数
formData	`x-www-form-urlencoded` 请求是的表单参数

数据类型枚举：

数据类型	对应实际类型
string	string
integer	int, uint, uint32, uint64
number	float32
boolean	bool
结构体	结构体类型

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

1.4 示例

通用 API 示例：

以下注释指定了文档的基本信息，以及基于 apikey 方式的一种安全校验方式：

go 复制代码

// @title Aurora Admin-API 文档
// @version v0.0.1
// @description Aurora 建站
// @contact.name nineya
// @contact.url https://www.nineya.com
// @contact.email 361654768@qq.com
// @schemes http https
// @host localhost:8888
// @BasePath /api/admin
// @produce json
// @securityDefinitions.apikey admin
// @in header
// @name Admin-Authorization

注解不能放在 @securityDefinitions 相关注解的后面，否则将不会被解析

接口 API 示例：

go 复制代码

// @summary Upload attachment by id
// @description Upload attachment by id
// @tags attachment
// @accept json
// @produce json
// @param id path id true "Attachment id"
// @param param body request.UpdateAttachmentParam true "Attachment name and team information"
// @success 200 {object} response.Response
// @security admin
// @router /attachment/{id} [put]

二、文档生成

使用命令下载 swag：

bash 复制代码

go install github.com/swaggo/swag/cmd/swag@latest

使用命令生成 swag 所需的文件：

bash 复制代码

swag init

这将会扫描源程序，解析注释并生成 docs 文件夹和文档信息文件。

三、与 Gin 集成

下载安装 gin-swagger ：

bash 复制代码

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

导入 docs下的文件：

go 复制代码

import (
   _ "go-project-name/docs"
)

添加 Gin 路由：

go 复制代码

swaggerGroup := router.Group("swagger")
swaggerGroup.GET("/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

通过 /swagger/index.html 可以访问到文档：

四、多文档

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

4.1 生成文档

要生成多份文档，在生成文档时就不能直接执行 swag init 命令了，需要指定更多的参数：

bash 复制代码

swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")，多个目录可用逗号分隔
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")

可分别为每份文档执行以下命令方法生成多份文档：

bash 复制代码

swag init -g 通用API所在Go文件 -d  API解析目录 --exclude 排除的目录 -o 文档输出目录 --instanceName 文档实例名

举例小玖的结构体对象所在目录为 internal/application/param，Admin 接口所在目录为internal/application/router/api/admin，Content 接口所在目录为 internal/application/router/api/content。

Admin 文档命令：

bash 复制代码

swag init -g index.go -d internal/application/router/api/admin,internal/application/param -o ./docs/admin --instanceName=admin

Content 文档命令：

bash 复制代码

swag init -g index.go -d internal/application/router/api/content,internal/application/param -o ./docs/content --instanceName=content

注意：

-g 参数的路径相对于 -d 参数的第一个路径。

如果 -d 指定的路径下没有 Go 文件，会有 execute go list command, exit status 1, stdout:, stderr:no Go files in ... 错误提示，无影响。

4.2 与 Gin 集成

导入 docs 下的文件：

go 复制代码

import (
   _ "go-project-name/docs/admin"
   _ "go-project-name/docs/content"
)

添加 Gin 路由：

go 复制代码

swaggerGroup := router.Group("swagger")
swaggerGroup.GET("/admin/*any", ginSwagger.WrapHandler(
  swaggerFiles.NewHandler(), func(config *ginSwagger.Config) {
    config.InstanceName = "admin"
  }))
swaggerGroup.GET("/content/*any", ginSwagger.WrapHandler(
  swaggerFiles.NewHandler(), func(config *ginSwagger.Config) {
    config.InstanceName = "content"
  }))

通过 /swagger/admin/index.html 和 /swagger/content/index.html 可以分别访问到两份文档。