swag

swag 是一个为Go 代码自动生成API 文档的工具，它为 gin, echo, fiber 等流行的web框架添加了开箱即用的插件，可以使现有的项目快速集成使用（swagger ui）

gin-swagger集成步骤

安装swag

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

安装gin-swagger

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

导入package并添加路由

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

...

router := gin.New()
router.GET("/swagger/*path", ginSwagger.WrapHandler(swaggerFiles.Handler))

添加注解

参照swag文档 添加通用注解（https://github.com/swaggo/swag#general-api-info）和API注解（https://github.com/swaggo/swag#api-operation） ,

通用注解

// @title example-server                    （服务名称）
// @version v0.2.4                              （服务版本）
// @contact.name gerrard                     （联系人）
// @contact.email [email protected]       （联系邮箱）
// @schemes http                                （协议） 

API注解

这里以一个健康检查接口API为例

// @Tags 非业务                                  (接口分类标签)
// @Summary health check api for k8s / apisix   (接口概述)
// @Description 监控检查接口，随机检查中间件是否连通</br>根据from的值进行检查, 如果是apisix则检查mysql是否连通</br>否则为k8s监控检查，会
检查redis是否连通                                 (接口详细说明)
// @Param from query string false "请求来源"     (参数说明)
// @Success 200                                 (成功返回)
// @Failure 500                                 (失败返回)
// @Router /healthz [GET]                       (路由及方法)
func (h *HealthzHandler) Healthz(c *gin.Context){
    ...
}

生成docs并导入

swag init

得到一个docs目录

docs
├── docs.go
├── swagger.json
└── swagger.yaml

将docs目录导入到项目中

import _ "github.com/gerrard_ynwa/example-server/docs"

重新编译启动服务

访问 127.0.0.1:28002/swagger/index.html 即可看到随服务一同发布的API文档了

微信扫一扫，订阅我的博客动态^_^