6f755a57a37630b8d31b809642c69a22
Gin(十):集成 Swagger

你喜欢写文档吗? 我喜欢

所以说文档成了开发心中的一个痛。尤其是使用 restful 接口,成了必须要写文档,否者前端同学根本不知道你写了什么。那么让我写文档,还不如杀了我呢!!!

接下来介绍一款神器 --- swagger

📜什么是swagger

Swagger 是一个 API 生成工具,可以生成文档。 Swagger 是通过编写 yamljson 来实现文档化。并且可以进行测试等工作。

通过 swagger 可以方便的生成接口文档,方便前端进行查看和测试。

🔧安装 swagger

上面说了一堆 swagger 怎么样,说到头还是要自己编写?其实并不是的,让我们的项目中集成 swagger,以后项目的接口文档便可以自动生成。

首先要安装 swagger

go get -u github.com/swaggo/swag/cmd/swag

等待安装完成,在我们的终端中执行 swag init,目录为根目录,于 main.go 同目录。

执行完成后,会在根目录下新建一个 docs 文件夹。

docs
|
|-docs.go
|-swagger.json
|-swagger.yaml

接下来就可以完善项目了。

将下面两行放入 initRouter 中的 import 中。

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 镜像。当然你也可以选择其他镜像代理。
Go Mod 代理设置

Go Mod 代理设置

等待包下载完成。

🍔集成 swagger

swagger 安装完成后,我们就可以对项目进行集成了。

initRouter 中添加路由,这个路由是对 swagger 的访问地址来进行添加的

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json")
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

其中 url 定义了 swaggerdoc.json 路径,我们可以直接访问该 json 来进行查看。

接下来就是完善文档的时间。

main.gomain 方法上添加注释。同时引入我们生成 docs.go

```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() {

top Created with Sketch.