# Gin(十):集成 Swagger 你喜欢写文档吗? ~~我喜欢~~。 所以说文档成了开发心中的一个痛。尤其是使用 `restful` 接口,成了必须要写文档,否者前端同学根本不知道你写了什么。那么让我写文档,还不如杀了我呢!!! 接下来介绍一款神器 — **swagger** # 什么是swagger `Swagger` 是一个 `API` 生成工具,可以生成文档。 `Swagger` 是通过编写 `yaml` 和 `json` 来实现文档化。并且可以进行测试等工作。 通过 `swagger` 可以方便的生成接口文档,方便前端进行查看和测试。 # 安装 swagger 上面说了一堆 `swagger` 怎么样,说到头还是要自己编写?其实并不是的,让我们的项目中集成 `swagger`,以后项目的接口文档便可以自动生成。 首先要安装 `swagger` 。 ```go go get -u github.com/swaggo/swag/cmd/swag ``` 等待安装完成,在我们的终端中执行 `swag init`,目录为根目录,于 `main.go` 同目录。 执行完成后,会在根目录下新建一个 `docs` 文件夹。 ```html docs | |-docs.go |-swagger.json |-swagger.yaml ``` 接下来就可以完善项目了。 将下面两行放入 `initRouter` 中的 `import` 中。 ```go swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" ``` 选择 `Sync packages of GinHello`,此时 `IDE` 就会自动帮我下载,并添加到 `go.mod` 中。 如果这里提示下载失败,请对 `go mod` 添加代理。 > **添加代理** File-Setting-Go-Go Modules(vgo)-Proxy > 代理添加 https://mirrors.aliyun.com/goproxy/ 这是最近阿里建立的 go mod 镜像。当然你也可以选择其他镜像代理。 > > ![配置页面](./img/10.1.jpeg) > > 等待包下载完成。 # 集成 swagger 对 `swagger` 安装完成后,我们就可以对项目进行集成了。 在 `initRouter` 中添加路由,这个路由是对 `swagger` 的访问地址来进行添加的 ```go url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url)) ``` 其中 `url` 定义了 `swagger` 的 `doc.json` 路径,我们可以直接访问该 `json` 来进行查看。 接下来就是完善文档的时间。 在 `main.go` 中 `main` 方法上添加注释。同时引入我们生成 `docs.go` ``` package main import ( _ "GinHello/docs" "GinHello/initRouter" ) // @title Gin swagger // @version 1.0 // @description Gin swagger 示例项目 // @contact.name youngxhu // @contact.url https://youngxhui.top // @contact.email youngxhui@g mail.com // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host localhost:8080 func main() { // 省略其他代码 } ``` 上述的注释基本都是很好理解的,不做过多解释。 主要的项目介绍注释就是这些,接下来进行我们的接口方法注释。 在我们的 `handler` 中添加注释 打开 `articleHandler.go` ,在 `Insert` 方法上添加。 ```go // @Summary 提交新的文章内容 // @Id 1 // @Tags 文章 // @version 1.0 // @Accept application/x-json-stream // @Param article body model.Article true "文章" // @Success 200 object model.Result 成功后返回值 // @Failure 409 object model.Result 添加失败 // @Router /article [post] ``` - @Summary 是对该接口的一个描述 - @Id 是一个全局标识符,所有的接口文档中 Id 不能标注 - @Tags 是对接口的标注,同一个 tag 为一组,这样方便我们整理接口 - @Version 表明该接口的版本 - @Accept 表示该该请求的请求类型 - @Param 表示参数 分别有以下参数 参数名词 参数类型 数据类型 是否必须 注释 属性(可选参数),参数之间用空格隔开。 - @Success 表示请求成功后返回,它有以下参数 请求返回状态码,参数类型,数据类型,注释 - @Failure 请求失败后返回,参数同上 - @Router 该函数定义了请求路由并且包含路由的请求方式。 具体参数类型,数据类型等可以查看[官方文档](https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html) 其中文档中没有说明的地方这里说明一下,关于 `Param` 的参数类型有以下几种 - query 形如 `\user?username=Jack&age=18` - body 需要将数据放到 body 中进行请求 - path 形如 `\user\1` 不同的参数类型对应的不同请求,请对应使用。 这样我们就完成了添加接口的文档注释。 我们用通用的方法来完善一下根据 `id` 查询数据的接口文档。 在 `GetOne` 的方法上添加如上注释。 ```go // @Summary 通过文章 id 获取单个文章内容 // @version 1.0 // @Accept application/x-json-stream // @Param id path int true "id" // @Success 200 object model.Result 成功后返回值 // @Router /article/{id} [get] ``` 我们对形如 `/article/:id` 的接口,最后的 id 通过 `{}` 包裹。 细心的小伙伴可能会发现我们最后的返回结果为 `model.Result` ,这是为了我们统一返回结果而新建的一个结构体,方便前端进行解析。具体函数如下 ```go package model type Result struct { Code int `json:"code" example:"000"` Message string `json:"message" example:"请求信息"` Data interface{} `json:"data" ` } ``` 我们在对 `Result` 中的 `tag` 会有 `example` ,这个仍旧是 `swagger` 的标签,用来给该结构体一个示例。 同理,我们可以对之前的 `article` 进行注释。 当我们完成了所有的代码注释时,在控制台中重新执行 `swag init`,它会根据我们的注释生成 `docs.go` 及其对应的 json 和 yaml 文件。 启动我们的项目,访问 `hppt://localhost:8080/swagger/index.html` 就可以查看我们的文档,效果如下 ![测试效果图](./img/10.2.jpeg) # 总结 通过本章节的学习,将我们的项目和文档相结合起来,反正要写注释,现在是一举两得,即完成了代码注释,也完成了项目文档。