日常web開發的專案，由於涉及與前端同事溝通，每次修改都要去更新api文件，比較惱火，但好在有款api生成利器-swagger。

本文主要介紹swagger的基本使用，如需深入瞭解學習，請前往官方：https://github.com/swaggo/gin-swagger

env

• go 1.19
• gin v1.8.1

下載swag

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

// 檢視swag命令
# swag --version
// swag.exe version v1.8.1

// 自己專案的根目錄執行init
# swag init
以下為response
2022/12/03 14:22:23 Generate swagger docs....
2022/12/03 14:22:23 Generate general API Info, search dir:./
2022/12/03 14:22:24 Generating request.RegisterRequest
2022/12/03 14:22:24 Generating response.Response
2022/12/03 14:22:24 create docs.go at  docs/docs.go
2022/12/03 14:22:24 create swagger.json at  docs/swagger.json
2022/12/03 14:22:24 create swagger.yaml at  docs/swagger.yaml
 

swag初始化後可以在根目錄看到：

接下來就是完善專案中的註解程式碼了

swagger 註解

路由註冊中新增swagger

如我的專案中的路由註冊如下：

package core

import (
	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"

	"xxx/internal/middleware"
	"xxx/internal/router"
)

// register router here
func 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)
	})
}
 

接著前往具體需要生成api文件的路由函式中添加註解：

...

import (
  _ "專案名/docs" // swagger 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) {
  ...
}
 

參考文件：

• Gin(十):整合 Swagger