白羊的空间

Go gin使用swagger生成API文档

本文代码github: https://github.com/zboyco/go-test/blob/master/gin-swagger/main.go

1. 前言

swagger 用于生成、描述、调用和可视化 RESTful 风格的API文档,这里记录下在go中使用swagger生成api文档的方法.

2. 库

1
2
github.com/swaggo/gin-swagger
github.com/swaggo/gin-swagger/swaggerFiles

以上两个库都需要使用,另外还需要一个swag工具用来生成docs文件.

1
github.com/swaggo/swag

验证swag是否安装成功

1
swag -v

3. 注释

swaggo通过注释来生成swagger需要的信息,详细的注释格式可以参考https://swaggo.github.io/swaggo.io ,这里只记录下简单的用法.

3.1. 项目信息

1
2
3
4
5
6
7
// @title Swagger Example API
// @version 1.0
// @description This is a sample server.

// @BasePath /
func main() {
}

3.2. 接口信息

1
2
3
4
5
6
7
8
9
// @Summary 获取文章
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /news [get]
func index(c *gin.Context) {
}

4. 使用

4.1. 首先引入包

1
2
"github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"

4.2. gin引擎添加GET方法

1
2
// use ginSwagger middleware to
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

4.3. 生成docs

控制台执行

1
swag init

4.4. 引入docs

引入swag生成的docs文件

1
import _ "./docs"

4.5. 运行

运行项目,浏览http://localhost:8080/swagger/index.html 即可访问API文档.

Golang goginswagger