系统接口

在现在的开发过程中还有很大一部分公司都是以口口相传的方式来进行前后端的联调，而接口文档很大一部分都只停留在了说说而已的地步，或者写了代码再写文档。 还有一点就是文档的修改，定义好的接口并不是一成不变的，可能在开发过程中文档修改不止一次的变化，这个时候就会很难受了。 只要不是强制性要求，没人会愿意写这东西，而且在写的过程中，一个字母的错误就会导致联调时候的很大麻烦，但是通过Swagger，我们可以省略了这一步，而且文档出错率近乎于零， 只要你在写代码的时候，稍加几个注解，文档自动生成。

使用方法

1. 入口文件设置swagger信息

package main

import (
    _ "gfast/boot"
    _ "gfast/router"
    "github.com/gogf/gf/frame/g"
)

// @title gfast API文档
// @version 1.0
// @description gfast 在线API文档
// @host localhost:8200
// @BasePath /
func main() {
    g.Server().Run()
}

2. 在控制层Controller的方法上添加注解来描述接口信息如:

// @Summary 信息列表
// @Description 信息列表
// @Tags 文章管理
// @Param data body cms_news.ReqListSearchParams true "data"
// @Success 0 {object} response.Response "{"code": 200, "data": [...]}"
// @Router /system/cms/news/list [get]
// @Security
func (c *CmsNews) List(r *ghttp.Request) {
    ...

3. 生成更新api接口文档

在 ./ 项目根目录下（和main.go文件同级目录下）执行：swag init -o ./swagger 生成或更新api文档。

执行后在项目根目录会自动生成swagger文件夹，其中保存了接口文档数据。

4. 后台访问系统工具 >> 系统接口即可查询文档

swaggo 详细文档地址请查阅：https://github.com/swaggo/swag