[go每日一库] go-gin 使用swagger生成api文档

日常web开发的项目，由于涉及与前端同事沟通，每次修改都要去更新api文档，比较恼火，但好在有款api生成利器-swagger。

本文主要介绍swagger的基本使用，如需深入了解学习，请前往官方：https://github.com/swaggo/gin-swagger

env

• go 1.19
• gin v1.8.1

下载swag

# go get -u github.com/swaggo/swag/cmd/swag

// 查看swag命令
# swag --version
// swag.exe version v1.8.1

// 自己项目的根目录执行init
# swag init
以下为response
2022/12/03 14:22:23 Generate swagger docs....
2022/12/03 14:22:23 Generate general API Info, search dir:./
2022/12/03 14:22:24 Generating request.RegisterRequest
2022/12/03 14:22:24 Generating response.Response
2022/12/03 14:22:24 create docs.go at  docs/docs.go
2022/12/03 14:22:24 create swagger.json at  docs/swagger.json
2022/12/03 14:22:24 create swagger.yaml at  docs/swagger.yaml

swag初始化后可以在根目录看到：

接下来就是完善项目中的注解代码了

swagger 注解

路由注册中添加swagger
如我的项目中的路由注册如下：

package core

import (
	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"

	"xxx/internal/middleware"
	"xxx/internal/router"
)

// register router here
func RegisterRouters(engine *gin.Engine)  {
	engine.MaxMultipartMemory = 8 << 20
	engine.Use(middleware.WebDebugLogMiddleware())
	// register system routers
	router.InitSystemRouter(engine)
	// register user routers
	router.InitUserRouter(engine)
	// register auth routers
	...
	// swagger doc api
	engine.GET("/swagger/*any", func(ctx *gin.Context) {
		ginSwagger.DisablingWrapHandler(swaggerfiles.Handler, "SWAGGER")(ctx)
	})
}

接着前往具体main和需要生成api文档的路由函数中添加注解：

...
// @title xxx
// @host localhost:8080
// ...
func main() { // main加上注解，需要导入docs
  ...
}


// register user
// @summary RegisterUser
// @Description register user
// @Tags RegisterUser
// @Accept json
// @Produce json
// @Param body body request.RegisterRequest true "请求body"
// @Success 200 {object} response.Response
// @Router /user/add [post]
func RegisterUser(ctx *gin.Context) { // handler加上注解
  ...
}

常用注解一览表

// 主要注解 - api
id: 全局标识符
tags: 相当于api的标题，可用来分组，同个tag为一个分组，方便整理接口
version：api版本
host：运行主机
router：路由，格式为：path []
summary: 与router同行的api summary
description: api的对应描述
accept: api的请求体允许的编码类型，可选项有：json | mpfd | xml
produce：api的响应体的编码类型，可选项有：同上
param：请求体的具体参数，格式：{param name} {param type} {data type} {is mandatory?} {comment attribute(optional)}，e.g. request body struct_xxx true 请求体
success：响应体的正常返回形式，格式：{return code or default} {param type} {data type} {commen}，e.g. 200 body struct_xxx 响应成功  
// 更多：当封装response时，指明具体data
// JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"

failure：响应体异常的返回形式，格式：同上

// 其他注解 - main
contact.name：项目联系人
contact.email：项目联系人的email
contact.url：项目地址

license.name：license name // 一看即知含义
license.url：

// param type
query
path
header
body
formData

// data type
string (string)
integer (int, uint, uint32, uint64)
number (float32)
boolean (bool)
user defined struct

官方文档：https://github.com/swaggo/swag/blob/master/README.md

当添加完注解后，接下来回到项目根目录重新执行swag init，swag命令会根据我们的注释生成 docs.go 及其对应的 json 和 yaml 文件。

启动服务看看swagger文档的效果：

可以看到已成功生成文档，后续有修改只需要修改路由函数对应的注解了，解放双手。

参考文档：

• Gin(十):集成 Swagger