swagger生成接口文档
转自
swagger生成接口文档
swagger介绍
Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档,代码生成和测试用例生成。
在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力。
最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新,而Swagger正是那种能帮我们解决接口文档问题的工具。
这里以gin框架为例,使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。
gin-swagger实战
想要使用gin-swagger
为你的代码自动生成接口文档,一般需要下面三个步骤:
- 按照swagger要求给接口代码添加声明式注释,具体参照声明式注释格式。
- 使用swag工具扫描代码自动生成API接口文档数据
- 使用gin-swagger渲染在线接口文档页面
第一步:添加注释
在程序入口main函数上以注释的方式写下项目相关介绍信息。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | package main // @title 这里写标题 // @version 1.0 // @description 这里写描述信息 // @termsOfService http://swagger.io/terms/ // @contact.name 这里写联系人信息 // @contact.url http://www.swagger.io/support // @contact.email support@swagger.io // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host 这里写接口服务的host // @BasePath 这里写base path func main() { r := gin.New() // liwenzhou.com ... r.Run() } |
在你代码中处理请求的接口函数(通常位于controller层)按如下方式写上注释:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | // GetPostListHandler2 升级版帖子列表接口 // @Summary 升级版帖子列表接口 // @Description 可按社区按时间或分数排序查询帖子列表接口 // @Tags 帖子相关接口 // @Accept application/json // @Produce application/json // @Param Authorization header string false "Bearer 用户令牌" // @Param object query models.ParamPostList false "查询参数" // @Security ApiKeyAuth // @Success 200 {object} _ResponsePostList // @Router /posts2 [get] func GetPostListHandler2(c *gin.Context) { // GET请求参数(query string):/api/v1/posts2?page=1&size=10&order=time // 初始化结构体时指定初始参数 p := &models.ParamPostList{ Page: 1, Size: 10, Order: models.OrderTime, } if err := c.ShouldBindQuery(p); err != nil { zap.L().Error( "GetPostListHandler2 with invalid params" , zap.Error(err)) ResponseError(c, CodeInvalidParam) return } data, err := logic.GetPostListNew(p) // 获取数据 if err != nil { zap.L().Error( "logic.GetPostList() failed" , zap.Error(err)) ResponseError(c, CodeServerBusy) return } ResponseSuccess(c, data) // 返回响应 } |
上面注释中参数类型使用了object
,models.ParamPostList
具体定义如下:
1 2 3 4 5 6 7 8 9 | // bluebell/models/params.go // ParamPostList 获取帖子列表query string参数 type ParamPostList struct { CommunityID int64 `json: "community_id" form: "community_id" ` // 可以为空 Page int64 `json: "page" form: "page" example: "1" ` // 页码 Size int64 `json: "size" form: "size" example: "10" ` // 每页数据量 Order string `json: "order" form: "order" example: "score" ` // 排序依据 } |
响应数据类型也使用的object
,我个人习惯在controller层专门定义一个docs_models.go
文件来存储文档中使用的响应数据model。
1 2 3 4 5 6 7 8 | // bluebell/controller/docs_models.go // _ResponsePostList 帖子列表接口响应数据 type _ResponsePostList struct { Code ResCode `json: "code" ` // 业务响应状态码 Message string `json: "message" ` // 提示信息 Data []*models.ApiPostDetail `json: "data" ` // 数据 } |
第二步:生成接口文档数据
编写完注释后,使用以下命令安装swag工具:
1 | go get -u github.com/swaggo/swag/cmd/swag |
在项目根目录执行以下命令,使用swag工具生成接口文档数据。
1 | swag init |
执行完上述命令后,如果你写的注释格式没问题,此时你的项目根目录下会多出一个docs
文件夹。
1 2 3 4 | ./docs ├── docs. go ├── swagger.json └── swagger.yaml |
第三步:引入gin-swagger渲染文档数据
然后在项目代码中注册路由的地方按如下方式引入gin-swagger
相关内容:
1 2 3 4 5 6 7 8 9 10 | import ( // liwenzhou.com ... _ "bluebell/docs" // 千万不要忘了导入把你上一步生成的docs gs "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" "github.com/gin-gonic/gin" ) |
注册swagger api相关路由
1 | r.GET( "/swagger/*any" , gs.WrapHandler(swaggerFiles.Handler)) |
把你的项目程序运行起来,打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文档了。
gin-swagger
同时还提供了DisablingWrapHandler
函数,方便我们通过设置某些环境变量来禁用Swagger。例如:
1 | r.GET( "/swagger/*any" , gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE" )) |
此时如果将环境变量NAME_OF_ENV_VARIABLE
设置为任意值,则/swagger/*any
将返回404响应,就像未指定路由时一样。
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· PostgreSQL 和 SQL Server 在统计信息维护中的关键差异
· DeepSeek “源神”启动!「GitHub 热点速览」
· 我与微信审核的“相爱相杀”看个人小程序副业
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 如何使用 Uni-app 实现视频聊天(源码,支持安卓、iOS)
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)