swag

github.com/swaggo/swag github.com/swaggo/gin-swagger

参考：

• gin-swagger
• swag

swaggo/swag 是 Swagger API 2.0 在 go 语言中的一个实现，通过在书写指定格式的注释就可以生成swagger.json和swagger.yaml类型的接口文档，方便导出和导入。 Swagger是 REST API 的一种 API 描述格式，现在的Swagger3.0也被称为OpenAPI规范。 Swag也提供了各种插件与现有框架结合使用，本次以gin框架的gin-swagger为例，其他框架集成swag的方法大同小异。

安装依赖

go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

编写注释

略，详见文档

生成文档

swag fmt
swag init

如上命令将格式化swag注释并生成文档在./docs目录下。

框架集成

在路由所在处添加如下依赖。项目名就是go.mod中的module。

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
import "<项目名>/docs" // docs is generated by Swag CLI, you have to import it.

路由中添加一行导航至swagger UI界面，BashPath没有特别设置用/就行。

docs.SwaggerInfo.BasePath = "/"
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

使用swag init生成文档后启动项目，访问localhost:8080/swagger/index.html就能看到接口文档了。