Gin框架使用swagger生成API文档

Swagger是基于标准的OpenAPI规范进行设计的。只要按照这套规范编写注解或通过扫描代码生成注解，就能生成统一标准的接口文档和一系列Swagger工具。

安装

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get -u github.com/alecthomas/template

验证安装是否成功。

> swag -v
swag version v1.7.0

写入注解

在安装完Swagger关联库后，就需要项目里的API接口编写注解，以便后续在生成时能够正确地运行。

1. 在main.go源代码中添加通用的API注释： ```go // @title 博客系统 // @version 1.0 // @description 简单的博客系统

func main() { gin.SetMode(global.ServerSetting.RunMode) router := routers.NewRouter() s := &http.Server{ Addr: “:8080”, Handler: router, TLSConfig: nil, ReadTimeout: 30, ReadHeaderTimeout: 0, WriteTimeout: 30, IdleTimeout: 0, MaxHeaderBytes: 1 << 20, TLSNextProto: nil, ConnState: nil, ErrorLog: nil, BaseContext: nil, ConnContext: nil, } //global.Logger.Info(“服务器启动成功，监听：”) _ = s.ListenAndServe() }

2. 在controller代码中添加API操作注释：
```go
type Tag struct {
}

func NewTag() Tag {
    return Tag{}
}

// @Summary 获取多个标签
// @Produce json
// @Tags 标签
// @Param name query string false "标签名称" maxlength(100)
// @Param state query int false "状态" Enums(0, 1) default(1)
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Success 200 {object} model.TagSwagger "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [get]
func (t Tag) List(ctx *gin.Context) {}

// @Summary 新增标签
// @Produce json
// @Tags 标签
// @Param name body string true "标签名称" minlength(3) maxlength(100)
// @Param state body int false "状态" Enums(0, 1) default(1)
// @Param created_by body string true "创建者" minlength(3) maxlength(100)
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [post]
func (t Tag) Create(ctx *gin.Context) {}

// @Summary 更新标签
// @Produce json
// @Tags 标签
// @Param id path int true "标签ID"
// @Param name body string true "标签名称" minlength(3) maxlength(100)
// @Param state body int false "状态" Enums(0, 1) default(1)
// @Param modified_by body string true "修改者" minlength(3) maxlength(100)
// @Success 200 {array} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags/{id} [put]
func (t Tag) Update(ctx *gin.Context) {}

// @Summary 删除标签
// @Produce json
// @Tags 标签
// @Param id path int true "标签ID"
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags/{id} [delete]
func (t Tag) Delete(ctx *gin.Context) {}

生成swagger文件

在编写完或更新完注解后，在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）：

> swag init
2021/06/14 15:31:21 Generate swagger docs....
2021/06/14 15:31:21 Generate general API Info, search dir:./
2021/06/14 15:31:21 Generating components.OperatorTask
2021/06/14 15:31:21 Generating components.Error
2021/06/14 15:31:21 create docs.go at docs/docs.go
2021/06/14 15:31:21 create swagger.json at docs/swagger.json
2021/06/14 15:31:21 create swagger.yaml at docs/swagger.yaml

可以看到在docs目录下，分别生成了docs.go、swagger.json、swagger.yaml文件。

添加访问路由

如何访问接口文件呢？直接添加一个路由即可。

import (
    _ "blog/docs"
    v1 "blog/internal/routers/api/v1"
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

func NewRouter() *gin.Engine {
    r := gin.New()
    r.Use(gin.Logger())
    r.Use(gin.Recovery())
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    tag := v1.NewTag()
    apiv1 := r.Group("/api/v1")
    {
        apiv1.POST("/tags", tag.Create)
        apiv1.DELETE("/tags/:id", tag.Delete)
        apiv1.PUT("/tags/:id", tag.Update)
        apiv1.PATCH("/tags/:id/state", tag.Update)
        apiv1.GET("/tags", tag.Get)
    }
    return r
}

查看接口文档

路由配置完成后，启动项目，即可在浏览器访问：http://127.0.0.1:8080/swagger/index.html，如下：

文章到这里就结束了，更多参数和配置请访问：https://github.com/swaggo/swag