Preface
在现如今前后端分离的模式下，前端如何快捷准确地确定接口类型、请求参数以及响应结构体，是开发中不可或缺的步骤，
与此同时，后端如何相应地即使反馈，也很重要，而 swagger 解决了这个问题，方便了前后端的联调测试，
接下来的内容主要是：在 Go 中使用 Gin 框架如何接入 swagger 服务，以及简易的代码包组织结构，
具体代码参考仓库：https://github.com/Eminem-x/Learning/tree/main/Go/gin-doc-cn/gin-swagger
Details
安装 swag
1
| go get -u github.com/swaggo/swag/cmd/swag
|
校验是否安装成功
在项目中安装 gin-swagger 依赖
1
2
| go get -u github.com/swaggo/gin-swagger
go get -u github.com.swaggo/gin-swagger/swaggerFiles // 如果报错，不影响使用
|
添加配置注解
具体路径，参考仓库代码即可
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
| package router
import (
"gin-swagger/services"
_ "gin-swagger/swagger/docs"
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
"log"
)
func InitRouter() {
r := gin.Default()
setRouter(r)
if err := r.Run(":8000"); err != nil {
log.Panicf("startup service failed, err:%v\n", err)
}
}
func setRouter(r *gin.Engine) {
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.GET("/login", services.Login)
}
|
注意以下的代码必须在 router 中引入，不然访问 swagger 会报 404
1
| r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
|
注释接口
详细的参数配置参考：https://github.com/swaggo/swag#general-api-info
示例代码（封装请求体、响应体、序列化）：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
func Login(c *gin.Context) {
_, _ = c.Writer.WriteString("Login!")
c.JSON(http.StatusOK, pkg.SuccessResponse{
Status: "200 OK",
Data: serializers.SerializeLogin(),
})
}
|
生成 swagger 文档
1
2
3
4
5
6
| -o 指定文档生成目录
-g 指定 swagger-info 所在的目录 默认 main.go
--parseDependency 解析外部依赖文件夹中的 go 文件，默认禁用，一般是在 init 生成文件时提示无法识别 struct 时添加
swag init -g router/router.go -o swagger/docs --parseDependency
rm -rf swagger && swag init -g router/router.go -o swagger/docs --parseDependency
|
生成 swagger 文档之后再在 router.go 文件中引入，引入下面内容：
1
| _ "gin-swagger/swagger/docs"
|
访问 swagger 界面
完成上述步骤之后启动项目，然后通过 http://localhost:port/swagger/index.html 访问即可