Gin 生成 Swagger 接口文档

Posted 2023-02-26 恋喵大鲤鱼

文章目录

• 1.背景
• 2.Swagger
• 3.准备工作
• • 安装 swag 命令
  • 添加声明式注释
  • 执行 swag init 生成接口描述文件
• 4.Gin 集成 Swagger
• • import 依赖包
  • import 生成的 docs 包
  • 注册 Gin router
• 5.FAQ
• 参考文献

1.背景

后台服务通过接口（如 RESTful API）对外提供服务时，需要有明确的接口文档。

书写接口文档，我们可以手动书写，也可以采用工具自动生成。手动书写的问题在于接口协议变更后需要维护接口文档，效率低下。采用工具生成，不同的工具生成的接口文档风格不一，增加阅读者的理解成本。

因此，我们可以采用业界常用的 Swagger 为 RESTful API 生成可交互的接口文档。

本文以 Gin 框架为例，描述 Gin 中如何为接口生成 Swagger 文档。

2.Swagger

Swagger 是一套基于 OpenAPI 规范实现的用于编写 RESTful API 文档的开源工具。可通过编写 yaml 和 json 来实现接口的文档化，并且可以进行测试等工作。

通过 Swagger 可以方便地生成接口文档，方便前端进行查看和测试。

Swagger 主要包含了以下三个部分：

• Swagger Editor

基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范(yaml 或 json 配置）。

• Swagger UI

他会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 RESTfulAPI。

• Swagger Codegen

它可以通过 OpenAPI 规范定义的任何 API 生成服务器存根和客户端SDK来简化构建过程。

使用 Swagger 就是把接口相关信息存储在它定义的描述文件里面（yaml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

3.准备工作

安装 swag 命令

首先本地需要先安装 swag 命令行工具。

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

swag 命令的作用是扫描程序文件，根据接口规范注释，生成接口描述文件（yaml或json格式）。

添加声明式注释

在源码中添加声明式注释，用于生成接口描述文件。

• General API Info

此类注释用于描述接口的一般信息，在 main() 函数处添加。如 title，version，description 等。

// @title XX管理系统后台接口。
// @version 1.0
// @description XX管理系统后台接口，供 APP 及 Web 端调用。
// @host https://xxx.xxx.com
// @basePath /api/v1
// @schemes https
// @accept json
// @produce json
func main() 
	// ...

• API Operation

此类注释用于描述接口的具体信息，在每一个接口函数处添加。如 Summary, Description, Tags 等。

Summary 是简短描述，Description 是详细描述，Tags 是逗号分隔的标签，用于分组。

// @Summary 检查 APP 包是否需要升级。
// @Description  检查 APP 包是否需要升级。
// @Tags APP 接口。
// @Accept json
// @Produce json
// @Param Body body ReqCheckAppUpgrade true "请求体"
// @Success 200 object RspCheckAppUpgrade
// @Router /app/check_app_upgrade [post]
func HandlerCheckAppUpgrade(c *gin.Context) 
	// ...

Param 表示请求参数，格式为：

param_name,param_type,data_type,is_mandatory,comment

其中 ReqCheckAppUpgrade 表示 body 使用的 struct。

Success 表示成功回包内容，其中 RspCheckAppUpgrade 表示回包 body 使用的 struct。

其他注释说明，详见 Declarative Comments Format。

执行 swag init 生成接口描述文件

在 main.go 所在目录，执行如下命令。

swag init

生成的接口描述文件将存入当前目录下的 docs 目录。

docs.go
swagger.json
swagger.yaml

或者指定相关选项。

swag init -g main.go -d apidir --parseDependency -o docs

swag init 具体用法参见：

swag init -h

4.Gin 集成 Swagger

生成 API 描述文件后，便可通过 Swagger 为我们提供的库，将 API 描述文件集成到服务中，通过接口的形式提供在线文档。

import 依赖包

package main

import (
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

import 生成的 docs 包

package main

import (
	_ "<your docs path>" // docs is generated by Swag CLI, you have to import it.
)

注册 Gin router

func main() 
	r := gin.New()
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
)

完成以上所有操作后，运行服务，浏览器访问：http://localhost:8080/swagger/index.html。

关于最终的文档效果，可参见官方示例 Swagger Petstore。

5.FAQ

（1）访问接口文档发生Failed to load API definition.错误。

原因是未 import 生成的 docs 包。

（2）执行 swag init会报错。

假如func方法头标注的swagger注释不正确，在自行根据报错信息去修改。

（3）访问接口文档报错 404 page not found。

是因为没有添加 Swagger 的路由。

（4）如果请求 Body 是 JSON 则无法添加注释，该如何给字段添加注释呢？

可以在请求 Body 对应的 struct 中添加注释，在接口的请求参数中添加说明。

// @Param Body body ReqCheckAppUpgrade true "字段描述参见 apis.ReqCheckAppUpgrade"

然后在接口文档中可找到 apis.ReqCheckAppUpgrade 的定义与字段描述。

---

参考文献

Swagger: API Documentation & Design Tools for Teams
github.com/swaggo/swag
Golang gin框架使用swagger生成接囗文档 - CSDN博客
Gin + Swagger快速生成API文档 - 稀土掘金