简述

写后端接口离不开 api 文档,目前 api 文档有两种方式:

  1. 程序生成
  2. 人工维护

人工维护和程序生成,两种方式的 api 文档方式,优缺点不言而喻了。相信基本都会通过程序生成 api 文档,下面介绍一下在 gin 钟整合 swagger 做为 api 文档。

swagger将注释添加到API源代码中,请参阅声明性注释格式。然后通过二进制命令生成接口文档。

swagger 整合

步骤

1.下载 go 的 swagger 包

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

2.编写 api 注释

这里使用之前的项目的test方法:


// test api
// @Summary 测试api
// @Description 通过接收username返回字符串
// @ID test-api
// @Accept  x-www-form-urlencoded
// @Produce  json
// @Param username path string true "用户名"
// @Success 200 {object} string
// @Header 200 {string} Token "qwerty"
// @Router /test [get]
func Test(c *gin.Context)  {
	//实例化一个TestRequest结构体,用于接收参数
	testStruct := requests.TestRequest{}

	//接收请求参数
	err := c.ShouldBind(&testStruct)

	//判断参数校验是否通过,如果不通过,把错误返回给前端
	if err != nil {
		c.JSON(http.StatusOK, gin.H{"error": requests.Translate(err)})
		return
	}
	//调用HelloService
	var service hello.HelloContract

	//这里使用的是接口定义了变量
	service = &hello.HelloService{}
	//调用服务的方法处理业务
	result := service.SayHello(testStruct.Username)

	//返回响应
	c.JSON(http.StatusOK, gin.H{"data": result})
}

3.生成文档

swag init

4.整合 swagger

在 main.go 中添加下面代码


import "cn.sockstack/gin_demo/docs"
import "github.com/swaggo/files"
import "github.com/swaggo/gin-swagger"

func main() {
    // 省略了 gin 部分的代码
    ...
    
    // 定义 swagger 相关信息
	docs.SwaggerInfo.Title = "Swagger Example API"
	docs.SwaggerInfo.Description = "This is a sample server Petstore server."
	docs.SwaggerInfo.Version = "1.0"
	docs.SwaggerInfo.Host = fmt.Sprintf("%s:%d", config.Server.Address, config.Server.Port)
	docs.SwaggerInfo.BasePath = "/"
	docs.SwaggerInfo.Schemes = []string{"http", "https"}
	
	// swagger api 路由
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

5.查看文档

浏览器访问http://127.0.0.1:8081/swagger/index.html,即可查看 swagger api 文档