接口文档 原创
1、swagger 简介
Swagger 是基于标准的 OpenAPI 规范进行设计的。只要按照这套规范编写注解或通过扫描代码生成注解,就能生成统一标准的接口文档和一系列 Swagger 工具。
2、依赖安装
go
$ 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
默认会将命令安装到 $GOPATH/bin
目录下,可以使用如下命令测试是否安装正常。
PS:我这是 win 环境
powershell
PS D:\my-dev\bin> .\swag.exe -v
swag.exe version v1.8.0
3、写入注解
在安装完 Swagger 关联库后,就需要项目里的 API 接口编写注解,以便后续在生成时能够正确地运行。
比如:
注解 | 描述 |
---|---|
@Summary | 摘要 |
@Produce | API 可以产生的 MIME 类型的列表,可以将 MIME 简单理解为响应类型,例如 JSON、XML、HTML 等 |
@Tags | 给 API 分组 |
@Param | 参数格式,从左到右分别为:参数名,参数类型,数据类型,是否必填,注释 |
@Success | 响应成功,从左到右分别为:状态码,参数类型,数据类型,注释 |
@Failure | 响应失败,从左到右分别为:状态码,参数类型,数据类型,注释 |
@Router | 路由,从左到右分别问:路由地址,HTTP 方法 |
由于我们还没有写太多的接口,所以先在 main
入口函数写一些简单的标识,如下:
go
// @title K8s管理平台
// @version 1.0
// @description 基于Gin+Vue开发的K8s管理平台
// @termsOfService https://github.com/joker-bai/kubemana.git
func main() {
......
}
然后再给 HelloWord 接口写上文档,在 internal/app/controllers/api/v1/helloworld.go
中,如下:
go
// @Summary HelloWorld
// @Produce json
// @Tags HelloWorld
// @Success 200
// @Router /api/ [get]
func (s *HelloWorldController) Get(ctx *gin.Context) {
ctx.JSON(
http.StatusOK, gin.H{
"Data": "Hello World",
},
)
}
4、生成文档
文档注解完成后,在项目根目录下执行 swag init
生成文档,输出如下:
并且会在项目根目录 docs
文件夹下生成如下文档:
5、添加路由
现在,我们仅需添加一条路由,就可以在服务启动过后访问 swagger ui。
在 initialize/router.go
中添加如下代码即可:
go
package initialize
import (
"github.com/gin-gonic/gin"
_ "github.com/joker-bai/kubemana/docs"
"github.com/joker-bai/kubemana/internal/app/routers"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
type injector interface {
Inject(router *gin.RouterGroup)
}
func (s *Engine) injectRouterGroup(router *gin.RouterGroup) {
{
for _, r := range []injector{
new(routers.HelloWorldRouter),
} {
r.Inject(router.Group("/api"))
}
}
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}
6、访问接口文档
路由配置完成后,启动项目,即可在浏览器访问:http://127.0.0.1:8080/swagger/index.html
,如下:
7、测试接口
现在点击 Try it out,可以测试接口访问是否正常。
可以看到接口测试正常。
8、代码版本
本节内容开发完成后,记得给代码标记,如下:
go
$ git add .
$ git commit -m "接口文档"