作为一个后端开发，给前端提供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] //路由信息，一定要写上 |
文章 go swagger 文档 转载需要注明出处
