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

安装

在项目目录下：

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

验证是否安装成功。

  1. >swag -v
  2. swag version v1.7.0

写入注解

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

注解 描述
@Summary 摘要
@Produce API可以产生的MIME类型的列表，可以将MIME简单理解为响应类型，例如JSON、XML、HTML等
@Tags 给API分组
@Param 参数格式，从左到右分别为：参数名，参数类型，数据类型，是否必填，注释
@Success 响应成功，从左到右分别为：状态码，参数类型，数据类型，注释
@Failure 响应失败，从左到右分别为：状态码，参数类型，数据类型，注释
@Router 路由，从左到右分别问：路由地址，HTTP方法

比如Tag的API：

  1. type Tag struct {
  2. }
  4. func NewTag() Tag {
  5.     return Tag{}
  6. }
  8. func (t Tag) Get(ctx *gin.Context) {}
  10. // @Summary 获取多个标签
  11. // @Produce json
  12. // @Tags 标签
  13. // @Param name query string false "标签名称" maxlength(100)
  14. // @Param state query int false "状态" Enums(0, 1) default(1)
  15. // @Param page query int false "页码"
  16. // @Param page_size query int false "每页数量"
  17. // @Success 200 {object} model.TagSwagger "成功"
  18. // @Failure 400 {object} errcode.Error "请求错误"
  19. // @Failure 500 {object} errcode.Error "内部错误"
  20. // @Router /api/v1/tags [get]
  21. func (t Tag) List(ctx *gin.Context) {}
  23. // @Summary 新增标签
  24. // @Produce json
  25. // @Tags 标签
  26. // @Param name body string true "标签名称" minlength(3) maxlength(100)
  27. // @Param state body int false "状态" Enums(0, 1) default(1)
  28. // @Param created_by body string true "创建者" minlength(3) maxlength(100)
  29. // @Success 200 {object} model.Tag "成功"
  30. // @Failure 400 {object} errcode.Error "请求错误"
  31. // @Failure 500 {object} errcode.Error "内部错误"
  32. // @Router /api/v1/tags [post]
  33. func (t Tag) Create(ctx *gin.Context) {}
  35. // @Summary 更新标签
  36. // @Produce json
  37. // @Tags 标签
  38. // @Param id path int true "标签ID"
  39. // @Param name body string true "标签名称" minlength(3) maxlength(100)
  40. // @Param state body int false "状态" Enums(0, 1) default(1)
  41. // @Param modified_by body string true "修改者" minlength(3) maxlength(100)
  42. // @Success 200 {array} model.Tag "成功"
  43. // @Failure 400 {object} errcode.Error "请求错误"
  44. // @Failure 500 {object} errcode.Error "内部错误"
  45. // @Router /api/v1/tags/{id} [put]
  46. func (t Tag) Update(ctx *gin.Context) {}
  48. // @Summary 删除标签
  49. // @Produce json
  50. // @Tags 标签
  51. // @Param id path int true "标签ID"
  52. // @Success 200 {object} model.Tag "成功"
  53. // @Failure 400 {object} errcode.Error "请求错误"
  54. // @Failure 500 {object} errcode.Error "内部错误"
  55. // @Router /api/v1/tags/{id} [delete]
  56. func (t Tag) Delete(ctx *gin.Context) {}

然后配置MAIN方法

  1. // @title 博客系统
  2. // @version 1.0
  3. // @description 简单的博客系统
  4. // @termsOfService https://github.com/qiaokebaba/blog_service
  6. func main() {
  7.     gin.SetMode(global.ServerSetting.RunMode)
  8.     router := routers.NewRouter()
  9.     s := &http.Server{
  10.         Addr:              ":" + global.ServerSetting.HttpPort,
  11.         Handler:           router,
  12.         TLSConfig:         nil,
  13.         ReadTimeout:       global.ServerSetting.ReadTimeout,
  14.         ReadHeaderTimeout: 0,
  15.         WriteTimeout:      global.ServerSetting.WriteTimeout,
  16.         IdleTimeout:       0,
  17.         MaxHeaderBytes:    1 << 20,
  18.         TLSNextProto:      nil,
  19.         ConnState:         nil,
  20.         ErrorLog:          nil,
  21.         BaseContext:       nil,
  22.         ConnContext:       nil,
  23.     }
  24.     //global.Logger.Info("服务器启动成功，监听：")
  25.     _ = s.ListenAndServe()
  27. }

生成swagger文件

在编写完或更新完注解后，在项目跟目录下，执行以下命令：

  1. > swag init
  2. 2021/02/03 11:43:40 Generate swagger docs....
  3. 2021/02/03 11:43:40 Generate general API Info, search dir:./
  4. 2021/02/03 11:43:41 Generating model.Tag
  5. 2021/02/03 11:43:41 Generating model.Model
  6. 2021/02/03 11:43:41 Generating errcode.Error
  7. 2021/02/03 11:43:41 create docs.go at docs\docs.go
  8. 2021/02/03 11:43:41 create swagger.json at docs\swagger.json
  9. 2021/02/03 11:43:41 create swagger.yaml at docs\swagger.yaml

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

添加访问路由

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

  1. import (
  2.     _ "code.coolops.cn/blog_services/docs"
  3.     v1 "code.coolops.cn/blog_services/internal/routers/api/v1"
  4.     "github.com/gin-gonic/gin"
  5.     swaggerFiles "github.com/swaggo/files"
  6.     ginSwagger "github.com/swaggo/gin-swagger"
  7. )
  9. func NewRouter() *gin.Engine {
  10.     r := gin.New()
  11.     r.Use(gin.Logger())
  12.     r.Use(gin.Recovery())
  13.     r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
  14.     article := v1.NewArticle()
  15.     tag := v1.NewTag()
  16.     apiv1 := r.Group("/api/v1")
  17.     {
  18.         apiv1.POST("/tags", tag.Create)
  19.         apiv1.DELETE("/tags/:id", tag.Delete)
  20.         apiv1.PUT("/tags/:id", tag.Update)
  21.         apiv1.PATCH("/tags/:id/state", tag.Update)
  22.         apiv1.GET("/tags", tag.Get)
  23.     }
  24.     return r
  25. }

查看接口文档

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

不定类型

在实际编写代码中，我们常常会遇到某个对象内的某个字段是interface，并且这个字段的类型是不定的，即公共结构体，比如：

  1. type Test struct{
  2.     Username string
  3.     Content interface{}
  4. }

对于这种方式的，就没有特别好的注解方式，官方给出的建议是就是定义一个针对 Swagger 的对象，专门用于Swagger接口文档的展示。

比如：

  1. type TagSwagger struct {
  2.     List []*Tag
  3.     Pager *app.Pager
  4. }

然后将注解处改为如下：

  1. // @Success 200 {object} model.TagSwagger "成功"

然后重新生成文件，只需执行以下命令

  1. swag init

最后的效果如下：
image.png