Go常用包(三十六):自动化文档生成[swagger]

1.介绍

1.1 什么是swagger

Swagger 是一套用于描述和文档化 RESTful API 的工具。它最初是由 Reverb Technologies 开发的，后来成为了 OpenAPI 规范的一部分。Swagger 提供了一种简单而直观的方式来定义、生成和可视化 API，帮助开发人员和团队更好地理解和使用 API。

1.2 swaggo

github.com/swaggo/swag 是一个开源项目，用于在 Go 语言中自动生成 Swagger 文档。它通过解析 Go 代码中的注释，生成符合 OpenAPI 规范的文档，从而简化了 API 文档的生成和维护过程。

源码地址: https://github.com/swaggo/swag，截止到(2024.06.18): Star 10K

主要功能

自动生成 Swagger 文档： swag 可以自动扫描 Go 代码中的注释和类型定义，生成 Swagger 文档。这样开发人员无需手动编写 Swagger 规范文件，减少了重复劳动和出错的可能性。
注释驱动：通过在 Go 代码中添加特定格式的注释，开发人员可以详细描述 API 的端点、请求参数、响应格式、错误码等。swag 工具会解析这些注释并生成相应的文档。
支持多种框架： swag 支持多种流行的 Go Web 框架，如 gin、echo、fiber 等。无论使用哪种框架，开发人员都可以轻松集成 swag 并生成 API 文档。
嵌入式 Swagger UI：生成的 Swagger 文档可以通过嵌入式 Swagger UI 页面查看和测试。开发人员可以直接在浏览器中查看API 文档，并进行交互式测试。

2.安装

2.1 下载swag

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

2.2 swag init 说明

$  swag init -h

NAME:
   swag init - Create docs.go

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

OPTIONS:
	 # 使日志记录静默。（默认：false）
   --quiet, -q 
   # API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --generalInfo value, -g value 
   # API解析目录 (默认: "./")
   --dir value, -d value 
   # 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --exclude value 
   # 结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --propertyStrategy value, -p value
   # 文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --output value, -o value 
   # 生成文件的输出类型（docs.go, swagger.json, swagger.yaml），如 go、json、yaml。（默认："go,json,yaml"）
   --outputTypes value, --ot value 
   #  是否解析vendor目录里的go源文件，默认不
   --parseVendor
   # 解析依赖文件夹中的 Go 文件，0:禁用，1:只解析模型，2:只解析操作，3:解析所有。（默认：0）
   --parseDependencyLevel value, --pdl value
   # 是否解析依赖目录中的go源文件，默认不
   --parseDependency, --pd
   # 指定API的描述信息所使用的markdown文件所在的目录
   --markdownFiles value, --md value
   # 解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --codeExampleFiles value, --cef value
   # 解析 internal 包中的go文件，默认禁用
   --parseInternal
   # 是否输出时间到输出文件docs.go的顶部，默认是
   --generatedTime 
   #  依赖解析深度 (默认: 100)
   --parseDepth value 
   # 默认情况下为所有字段设置验证要求。（默认：false）
   --requiredByDefault 
   # 设置文档实例名 (默认: "swagger")
   --instanceName value   
   # 读取全局类型覆盖的文件。（默认：".swaggo"）
   --overridesFile value    
   # 通过 'go list' 解析依赖项。（默认：true）
   --parseGoList 
   # 仅解析与给定扩展名匹配的操作。
   --parseExtension value 
   # 用于筛选生成文档的 API 标签列表，使用逗号分隔。特殊情况：如果标签前缀为 '!' 字符，则会排除带有该标签的 API
   --tags value, -t value 
   # 提供 Go 模板生成的自定义分隔符。格式为 leftDelim,rightDelim，例如："[[,]]"。
   --templateDelims value, --td value 
   #  docs.go 的包名，默认使用输出目录名称（参见 --output 选项）
   --packageName --output 
   # 设置默认的集合格式。（默认："csv"）
   --collectionFormat value, --cf value 
   # 仅解析导入路径匹配给定前缀的包，使用逗号分隔
   --packagePrefix value 
   # 为 swagger.json 设置主机状态。
   --state value

3. 快速使用

下面以集成到Gin框架为示例，进行快速入门

3.1 安装依赖

# 在 Gin 应用中集成 Swagger UI
$ go get -u github.com/swaggo/gin-swagger
# 将 Swagger UI 的静态文件集成到你的 Go Web 应用程序中
$ go get -u github.com/swaggo/files

3.2 Swagger封装

import (
	"fmt"
	"github.com/gin-gonic/gin"
    "52lu/gin-api-template/docs"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

/*
* @Description: swagger初始化
* @Author: LiuQHui
* @Receiver h
* @Param engine
* @Date 2024-06-18 16:53:45
 */
func SwaggerInit(engine *gin.Engine) {
  // 获取swagger
	swaggerInfo := docs.SwaggerInfo
	// 动态设置Swagger
	swaggerInfo.Title = "GinApiDemo"
	swaggerInfo.Description = "基于Gin框架，开发api通用框架模版"
	swaggerInfo.Version = "v1.0.0"
	swaggerInfo.Host = "0.0.0.0:8800"
	swaggerInfo.BasePath = ""
	// Serve Swagger UI
	engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

3.3 调用函数

// 其他逻辑
...
// gin实例
r := gin.Default()
...
// 调用函数
SwaggerInit(r)

3.4 接口编写

1.Get接口

type DemoResp struct {
  // 用户id
	Id int64 `json:"id"`
	// 姓名
	Name string `json:"name"`
	// 年龄
	Age int `json:"age"`
	// 登录令牌
	Token string `json:"token"`
	// 最后登录时间
	LastLoginTime string `json:"last_login_time"`
	// 创建时间
	CreateTime string `json:"create_time"`
}

//	@Summary	Get参数
//	@Tags		演示模块
//	@Accept		json
//	@Produce	json
//	@Param		x-token	header		string	true	"令牌"
//	@Param		name	query		string	true	"姓名"	example("小花")
//	@Param		age		query		int		true	"年龄"	default(15)
//	@success	200		{object}	ginutil.Response{data=apitype.DemoResp}
//	@Router		/api/demo/get [get]
func (d *DemoApiController) Get(ctx *gin.Context) {
	ctx.JSON(200, map[string]interface{}{
		"token": ctx.Request.Header.Get("x-token"),
		"name":  ctx.Request.URL.Query().Get("name"),
		"age":   ctx.Request.URL.Query().Get("age"),
	})
}

2.POST接口

type DemoRequest struct {
	// 认证令牌，从 header 中获取
	// required: true
	XToken string `header:"X-Token" json:"XToken,omitempty"`
	// 姓名
	// required: true
	Name string `json:"name" form:"name" example:"张三" `
	// 年龄
	// required: true
	Age int `json:"age" form:"age" example:"18"`
}

//	@Summary	Post参数
//	@Tags		演示模块
//	@Accept		json
//	@Produce	json
//	@Param		x-token	header		string				true	"令牌"
//	@Param		request	body		apitype.DemoRequest	true	"请求参数"
//	@success	200		{object}	ginutil.Response{data=apitype.DemoResp}
//	@Router		/api/demo/post [post]
func (d *DemoApiController) Post(ctx *gin.Context) {
	// 接收参数
	var param apitype.DemoRequest
	err := ctx.ShouldBindBodyWith(&param, binding.JSON)
	if err != nil {
		ginutil.FailMsg(ctx, err.Error())
		return
	}
	ctx.JSON(200, map[string]interface{}{
		"token": ctx.Request.Header.Get("x-token"),
		"param": param,
	})
}

3. 文档注释说明

注释	描述
@Summary	描述接口的具体作用
@Tags	`API`所属的模块列表，多个以逗号分隔。
@Accept	`API` 可以使用的`MIME`类型列表。请注意，`Accept` 仅影响具有请求正文的操作，例如 `POST、PUT 和 PATCH`。值必须如“Mime类型”中所述。
@Produce	`API`可以生成的`MIME`类型的列表。值必须如“Mime类型”中所述。
@Param	指定参数信息;格式: `@Param 参数名参数类型数据类型必填字段描述示例:example("x")`
@success	描述`API`响应成功时,返回的数据结构示例
@Router	指定`API`访问路径，要和真实一致