go-gin 使用swagger生成api文档教程

日常web开发的项目，每次修改都要去更新api文档，比较恼火，但好在有款api生成利器-swagger。

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

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

1

在Go项目根文件夹中运行Swag

在main.go所在目录执行 swag init, -g 参数是输出详细信息

执行后，会生成docs/doc.go以及docs/swagger.json,docs/swagger.yaml

$ swag init

下载gin-swagger

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

$ go get -u github.com/swaggo/files

接下来就是完善项目中的注解代码了
swagger 注解
路由注册中添加swagger
如我的项目中的路由注册如下：

package coreimport ( "github.com/gin-gonic/gin" swaggerfiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" "xxx/internal/middleware" "xxx/internal/router")// register router herefunc 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加上注解 ...}

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

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

启动服务看看swagger文档的效果：
http://localhost:port/swagger/index.html

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