接口文档 原创

1、swagger 简介

Swagger 是基于标准的 OpenAPI 规范进行设计的。只要按照这套规范编写注解或通过扫描代码生成注解，就能生成统一标准的接口文档和一系列 Swagger 工具。

2、依赖安装

$ 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 环境

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 入口函数写一些简单的标识，如下：

// @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 中，如下：

// @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 中添加如下代码即可：

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、代码版本

本节内容开发完成后，记得给代码标记，如下：

$ git add .
$ git commit -m "接口文档"