基于golang的swagger超贴心、超详细使用指南【有很多坑】

Swagger 相关的工具集会根据 OpenAPI 规范去生成各式各类的与接口相关联的内容，常见的流程是编写注解 =》调用生成库-》生成标准描述文件 =》生成/导入到对应的 Swagger 工具。

安装

因此接下来第一步，我们要先安装 Go 对应的开源 Swagger 相关联的库，在项目 blog-service 根目录下执行安装命令，如下：

$ 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.6.5

此处有坑：go get命令分两步：第一步如同git clone拉取github上的依赖并下载，第二步就是会go install编译，这个swagger包比较特殊，go install编译会编译出可执行文件，然后放在GOBIN。因此GOBIN的目录选择一定要选在可读可写权限目录下，如果你放在只读文件夹下，会安装不了swagger的可执行文件的！！！会报错：access denied提醒权限不够

写入注解

在完成了 Swagger 关联库的安装后，我们需要针对项目里的 API 接口进行注解的编写，以便于后续在进行生成时能够正确的运行，接下来我们将使用到如下注解：

注解	描述
@Summary	摘要
@Produce	API 可以产生的 MIME 类型的列表，MIME 类型你可以简单的理解为响应类型，例如：json、xml、html 等等
@Param	参数格式，从左到右分别为：参数名、入参类型、数据类型、是否必填、注释
@Success	响应成功，从左到右分别为：状态码、参数类型、数据类型、注释
@Failure	响应失败，从左到右分别为：状态码、参数类型、数据类型、注释
@Router	路由，从左到右分别为：路由地址，HTTP 方法
2.4.4.1 API
我们切换到项目目录下的 internal/routers/api/v1 目录，打开 tag.go 文件，写入如下注解：

// @Summary 获取多个标签
// @Produce  json
// @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.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [get]
func (t Tag) List(c *gin.Context) {}

// @Summary 新增标签
// @Produce  json
// @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(c *gin.Context) {}

// @Summary 更新标签
// @Produce  json
// @Param id path int true "标签 ID"
// @Param name body string false "标签名称" 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(c *gin.Context) {}

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

在这里我们只展示了标签模块的接口注解编写，接下来你应当按照注解的含义和参考上述接口注解，完成文章模块接口注解的编写。

main注解

那么接口方法本身有了注解，那针对这个项目，能不能写注解呢，万一有很多个项目，怎么知道它是谁？实际上是可以识别出来的，我们只要针对 main 方法写入如下注解：

// @title 博客系统
// @version 1.0
// @description Go 语言编程之旅：一起用 Go 做项目
// @termsOfService https://github.com/go-programming-tour-book
func main() {
	...
}

生成

在完成了所有的注解编写后，我们回到项目根目录下，执行如下命令：

$ swag init

在执行命令完毕后，会发现在 docs 文件夹生成 docs.go、swagger.json、swagger.yaml 三个文件。

路由

那注解编写完，也通过 swag init 把 Swagger API 所需要的文件都生成了，那接下来我们怎么访问接口文档呢？其实很简单，我们只需要在 routers 中进行默认初始化和注册对应的路由就可以了，打开项目目录下的 internal/routers 目录中的 router.go 文件，新增代码如下：

import (
	...
	_ "github.com/go-programming-tour-book/blog-service/docs"
	//_ 表示执行init函数时调用改包，需要将这个替换为自己本地的docs目录路径。这个路径是github上别人的docs,此处只是用来测试。
	//此处应该这样写：_ "swagger_demo/docs"
	//上面的swagger_demo为本项目名称，docs就是swag init自动生成的目录，用于存放 docs.go、swagger.json、swagger.yaml 三个文件。
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
)

func NewRouter() *gin.Engine {
	r := gin.New()
	r.Use(gin.Logger())
	r.Use(gin.Recovery())
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	...
	return r
}

从表面上来看，主要做了两件事，分别是初始化 docs 包和注册一个针对 swagger 的路由，而在初始化 docs 包后，其 swagger.json 将会默认指向当前应用所启动的域名下的 swagger/doc.json 路径，如果有额外需求，可进行手动指定，如下：

url := ginSwagger.URL("http://127.0.0.1:8000/swagger/doc.json")
  r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

查看接口文档

在完成了上述的设置后，我们重新启动服务端，在浏览器中访问 Swagger 的地址 http://127.0.0.1:8000/swagger/index.html，就可以看到上述图片中的 Swagger 文档展示，其主要分为三个部分，分别是项目主体信息、接口路由信息、模型信息，这三部分共同组成了我们主体内容。

快速上手文档:swag使用指南

官方文档:swagger详细使用指南

ps：上不去的话，挂个梯子