You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

182 lines
5.9 KiB

4 years ago
# 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)
# 总结
通过本章节的学习,将我们的项目和文档相结合起来,反正要写注释,现在是一举两得,即完成了代码注释,也完成了项目文档。