简介

Swagger 本质上是一种用于描述使用 JSON 表示的RESTful API的接口描述语言。Swagger 与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger 包括自动文档，代码生成和测试用例生成。
在前后端分离的项目开发过程中，如果后端能够提供一份清晰明了的接口文档，那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的，而且后续接口文档的维护也十分耗费精力。
最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新，而 Swagger 正是那种能帮我们解决接口文档问题的工具。

集成

想要使用 gin-swagger 为代码自动生成接口文档，一般需要下面三个步骤：

1. 按照 swagger 要求给接口代码添加声明式注释，具体参照声明式注释格式。
2. 使用 swag 工具扫描代码自动生成 API 接口文档数据
3. 使用 gin-swagger 渲染在线接口文档页面

第一步：添加注释

在程序入口 main 函数上以注释的方式写下项目相关介绍信息。

package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
func main() {
 r := gin.New()

 r.Run()
}

在你代码中处理请求的接口函数（通常位于 controller 层）按如下方式写上注释：

// GetPostListHandler2 升级版帖子列表接口
// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamPostList false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]
func GetPostListHandler2(c *gin.Context) {
 p := &models.ParamPostList{
  Page:  1,
  Size:  10,
  Order: models.OrderTime,
 }
 ...
}

上面注释中参数类型使用了 object，models.ParamPostList 具体定义如下：

// bluebell/models/params.go

// ParamPostList 获取帖子列表query string参数
type ParamPostList struct {
 CommunityID int64  `json:"community_id" form:"community_id"`   // 可以为空
 Page        int64  `json:"page" form:"page" example:"1"`       // 页码
 Size        int64  `json:"size" form:"size" example:"10"`      // 每页数据量
 Order       string `json:"order" form:"order" example:"score"` // 排序依据
}

响应数据类型也使用的 object，在 controller 层专门定义一个 docs_models.go 文件来存储文档中使用的响应数据 model。

// bluebell/controller/docs_models.go

// _ResponsePostList 帖子列表接口响应数据
type _ResponsePostList struct {
 Code    ResCode                 `json:"code"`    // 业务响应状态码
 Message string                  `json:"message"` // 提示信息
 Data    []*models.ApiPostDetail `json:"data"`    // 数据
}

第二步：生成接口文档数据

编写完注释后，使用以下命令安装 swag 工具：

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

# 1.16 及以上版本
go install github.com/swaggo/swag/cmd/swag@latest

在项目根目录执行以下命令，使用 swag 工具生成接口文档数据。

swag init

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个 docs 文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

第三步：引入 gin-swagger 渲染文档数据

然后在项目代码中注册路由的地方按如下方式引入 gin-swagger 相关内容：

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"

    _ "bluebell/docs"
)

注册 swagger api 相关路由

func main() {
    r := gin.Default()

    ...

    r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

把程序运行起来，打开浏览器访问 http://localhost:8080/docs/index.html 就能看到 Swagger 2.0 Api 文档了。

通用 API 信息

示例

API 操作

示例