作为一个后端开发,给前端提供api接口是必须的。手动去写文档不是一个程序员的风格。swagger就是一个很好的api文档生成该工具,go当然也支持了。下面看看怎么使用这个工具。
1、安装需要用到的包
1 2 3 4 5 |
# 安装swagger cmd go get -u github.com/swaggo/swag/cmd/swag # 显示swagger版本 swag -v |
安装完成后检查命令是否可用,如果不行执行,请将$GOPATH/bin
加入到 $PATH当中去。在windows中可以在下载源码后,自己编译生成swag.exe程序。后续把exe文件拷贝到项目根目录下面执行swag.exe, init
也是一样的。
安装以下两个包
1 2 |
go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/gin-swagger/swaggerFiles |
执行初始化命令
1 |
swag init // 注意,一定要和main.go处于同一级目录 |
初始化命令,在根目录生成一个docs文件夹
docs/docs.go
在路由上添加一个swagger访问地址
1 2 3 4 5 6 7 8 9 10 11 12 13 |
import ( _ "ginfast/docs" // 这个不能漏掉 "github.com/gin-gonic/gin" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" ) func ApiRouter() *gin.Engine { // 实例router r := gin.Default() r.GET("/doc/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) return r; } |
写注释
1 2 3 4 5 6 7 8 9 10 11 12 |
// @Summary 查询所有用户 // @Description 查询所有用户 // @Tags 用户 // @Accept json // @Produce json // @Success 200 {array} models.User // @Router /api/user [get] func (u *userController) FindAll(c *gin.Context) { all := service.UserService.FindAll() response.Json.SetData(all).SetCode(dist.MessageSuccess).Ok(c) return } |
再次执行初始化命令
1 |
swag init --parseDependency --parseInternal |
访问:http://ip:port/doc/index.html
注意事项
1、假如func方法头标注的swagger注释不正确,在执行swag init
会报错,自行根据报错信息去修改;
2、访问swagger控制台报错404 page not found
,是因为没有添加swagger的路由:router.GET("/swagger/*any",ginSwagger.WrapHandler(swaggerFiles.Handler, url));
3、访问swagger控制台报错Failed to load spec
,是因为没有import引入执行swag init
生成的swagger的docs文件夹;
附上Swagger的注解
1 2 3 4 5 6 7 8 9 10 |
// @Summary 接口概要说明 // @Description 接口详细描述信息 // @Tags 用户信息 //swagger API分类标签, 同一个tag为一组 // @accept json //浏览器可处理数据类型,浏览器默认发 Accept: */* // @Produce json //设置返回数据的类型和编码 // @Param id path int true "ID" //url参数:(name;参数类型[query(?id=),path(/123)];数据类型;required;参数描述) // @Param name query string false "name" // @Success 200 {object} Res {"code":200,"data":null,"msg":""} //成功返回的数据结构, 最后是示例 // @Failure 400 {object} Res {"code":200,"data":null,"msg":""} // @Router /test/{id} [get] //路由信息,一定要写上 |