Gin 生成 Swagger 接口文档

Posted 恋喵大鲤鱼

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Gin 生成 Swagger 接口文档相关的知识,希望对你有一定的参考价值。

文章目录

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文档 - 稀土掘金

以上是关于Gin 生成 Swagger 接口文档的主要内容,如果未能解决你的问题,请参考以下文章

golang gin框架 集成swagger 自动生成文档

Go语言-整合gin-swagger生成API文档

# 聊一聊悟空编辑器 #Gin + Swagger快速生成API文档

golang gin框架 使用swagger生成api文档

Gloang Swagger——自动生产接口文档

Golang Gin 项目使用 Swagger