golang swaggo 生成 swagger 文档

简介

swaggo 是一个开源项目，它能将 go 注释转换为 swagger 2.0 文档，且目前已经适配了多种流行框架，提供了插件允许与现有的 Go 项目快速集成。

安装

在你的项目根目录下执行：

go install github.com/swaggo/swag/cmd/swag@latest

命令会将 swaggo 的可执行程序安装到你的 GOPATH/bin 目录下。

初始化 / 更新文档

在项目中编写 go swaggo 注释后，在你的 main 文件所在目录下执行初始化命令：

swag init -g main.go -o docs

• main.go 代表你的启动文件名称
• -o docs 指定文档生成的目录

执行完毕后会在执行目录下 docs 目录下生成 docs.go，swagger.json，swagger.yml 文件，其中 docs.go 是swagger 首页 html 的加载文件以及通用信息的初始化，swagger.json 和 swagger.yml 是 api 的描述文件。

gin 使用 swaggo

gin 整合 swaggo 很简单，主要是在 gin 的路由添加少量配置就可以。

代码实例：

// @securityDefinitions.apikey ACCESS_TOKEN
// @in header
// @name access_token
// @Security ACCESS_TOKEN
func main() {

    // 如果 swaggo 注释在其他包下，需要 import 一下

    initDocsInfo()
    engine := gin.Default()

    engine.Use(cors.New(corsConfig()))

    // 注册 swagger api
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    engine.GET("/swaggo/get/:id", GetFunc)
    engine.POST("/swaggo/post", PostFunc)

    engine.Run("127.0.0.1:8080")

}

// 修改生成的 swagger 通用信息
func initDocsInfo() {
    docs.SwaggerInfo.Version = "1.0.0"
    docs.SwaggerInfo.Host = "127.0.0.1:8080"
    docs.SwaggerInfo.BasePath = "/"
    docs.SwaggerInfo.Title = "Swaggo API"
    docs.SwaggerInfo.Schemes = []string{"http", "https"}
}

func corsConfig() cors.Config {
    corsConf := cors.Config{}
    corsConf.AllowAllOrigins = true
    return corsConf
}

• main 函数上方的注释为 header 定义，指定 api 请求需要 access token。
• ginSwagger.WrapHandler(swaggerFiles.Handler) 注册 gin swaggo 的资源。
• initDocsInfo 函数用于初始化 docs.go 文件中 swagger 的通用信息。
• 添加 cors 防止跨域。

api 定义示例：

type ViewVO struct {
    // 字符串
    String string `json:"string"`
    // 布尔
    Bool bool `json:"bool"`
    // 数字
    Number int `json:"number"`
}

// @Tags api
// @Router /swaggo/get/{id} [get]
// @Summary get
// @Description get
// @Security ACCESS_TOKEN
// @Accept  json
// @Produce  json
// @Param id path string false "id"
// @Param string query string false "字符串"
// @Param bool query bool false "布尔"
// @Param number query int false "数字"
// @success 200 {object} ViewVO
func GetFunc(ctx *gin.Context) {
    ctx.JSON(200, "GetFunc")
}

// @Tags api
// @Router /swaggo/post [post]
// @Summary post
// @Description post
// @Security ACCESS_TOKEN
// @Accept  json
// @Produce  json
// @Param params body ViewVO true "params"
// @success 200 {array} ViewVO
func PostFunc(ctx *gin.Context) {
    ctx.JSON(200, "PostFunc")
}

启动服务后访问 http://localhost:8080/swagger/index.html，生成的 swagger 页面如下：

beego 使用 swaggo

由于 beego 框架本身自带的 beego docs 我觉得不是很好用，所以使用 swaggo 也是个不错的选择。

虽然 swaggo 官方不支持 beego，但是实现也比较简单，我们只需要先下载 swagger 的静态资源再读取就可以了。

1. 在项目根目录下创建 docs 目录，下载静态资源文件：

2. 将其中的 index.html 读取 swagger json 的请求接口修改一下，之后我们在 beego 中添加这个接口即可：

<script>
  window.onload = function() {
    // Begin Swagger UI call region
    const ui = SwaggerUIBundle({
      // 修改为我们自己的接口
      url: "/swagger/json",
      // 以下忽略
  };
</script>

3. 使用命令在 docs 目录下生成 docs.go 与 swagger.json 文件：

swag init -g main.go -o docs

代码示例：

// @securityDefinitions.apikey ACCESS_TOKEN
// @in header
// @name access_token
// @Security ACCESS_TOKEN
func main() {
    // 放行静态资源
    beego.BConfig.WebConfig.DirectoryIndex = true
    beego.BConfig.WebConfig.StaticDir["/swagger"] = "docs"

    // cors
    beego.InsertFilter("*", beego.BeforeRouter, cors.Allow(&cors.Options{
       AllowAllOrigins: true,
    }))

    // 获取 swagger.json 的接口
    beego.Get("/swagger/json", docs.SwaggerJson)

    beego.Get("/swaggo/get/:id", GetFunc)
    beego.Post("/swaggo/post/", PostFunc)

    docs.Init("1.0.0", "127.0.0.1:8080", "/", "Swaggo API")

    beego.Run("127.0.0.1:8080")
}

// package docs

// Init 修改生成的 swagger 通用信息
func Init(version, host, basePath, title string) {
    SwaggerInfo.Version = version
    SwaggerInfo.Host = host
    SwaggerInfo.BasePath = basePath
    SwaggerInfo.Title = title
    SwaggerInfo.Schemes = []string{"http", "https"}
}

func SwaggerJson(ctx *context.Context) {
    json, _ := swag.ReadDoc(SwaggerInfo.InfoInstanceName)
    ctx.WriteString(json)
}

api 定义示例

type ViewVO struct {
    // 字符串
    String string `json:"string"`
    // 布尔
    Bool bool `json:"bool"`
    // 数字
    Number int `json:"number"`
}

// @Tags api
// @Router /swaggo/get/{id} [get]
// @Summary get
// @Description get
// @Security ACCESS_TOKEN
// @Accept  json
// @Produce  json
// @Param id path string false "id"
// @Param string query string false "字符串"
// @Param bool query bool false "布尔"
// @Param number query int false "数字"
// @success 200 {object} ViewVO
func GetFunc(ctx *context.Context) {
    ctx.WriteString("GetFunc")
}

// @Tags api
// @Router /swaggo/post [post]
// @Summary post
// @Description post
// @Security ACCESS_TOKEN
// @Accept  json
// @Produce  json
// @Param params body ViewVO true "params"
// @success 200 {array} ViewVO
func PostFunc(ctx *context.Context) {
    ctx.WriteString("PostFunc")
}

启动服务后访问 http://localhost:8080/swagger/index.html 即可看到生成的 swagger 页面。

最后

swaggo 的详细用法可参考官方文档：swaggo。

文中示例代码已经上传仓库：igolang。