去语言使用大摇大摆生成接口文档的方法

　　

　　

在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力。

　　

这里以杜松子酒框架为例,使用gin-swagger库以使用大摇大摆2.0自动生成RESTful API文档。

　　

　　

在程序入口主要函数上以注释的方式写下项目相关介绍信息。

　　 　　 　　主要包//@title这里写标题//@version 1.0//@description这里写描述信息//@termsOfService http://swagger.io/terms///@contact.name这里写联系人信息//@contact。url http://www.swagger.io/support//@contact。电子邮件support@swagger.io//@license.name Apache 2.0//@license。url http://www.apache.org/licenses/LICENSE-2.0.html//@host这里写接口服务的主机//@BasePath这里写的基本路径 　　函数main () { 　　r:=gin.New ()//liwenzhou.com… 　　 　　r.Run () 　　} 　　 　　

//GetPostListHandler2升级版帖子列表接口//@Summary升级版帖子列表接口//@Description可按社区按时间或分数排序查询帖子列表接口//@ tags帖子相关接口//@Accept application/json//@Produce application/json//@Param授权头字符串错误“无记名用户令牌”//@Param对象查询模型。ParamPostList false”查询参数”//@Security ApiKeyAuth//{对象}_ResponsePostList @Success 200//@Router/posts2(得到) 　　func GetPostListHandler2 (c * gin.Context) {//得到请求参数(查询字符串):/api/v1/posts2& # 63;页面=1,大?10,o=)的时间//初始化结构体时指定初始参数 　　p:=, models.ParamPostList { 　　页:1、 　　大小:10 　　顺序:models.OrderTime、 　　} 　　 　　如果犯错:=c.ShouldBindQuery (p);犯错!=nil { 　　zap.L ()。错误(“GetPostListHandler2无效参数”,zap.Error (err)) 　　CodeInvalidParam ResponseError (c) 　　返回 　　} 　　数据,犯错:=logic.GetPostListNew (p)//获取数据 　　如果犯错!=nil { 　　zap.L () . error (“logic.GetPostList()失败”,zap.Error (err)) 　　CodeServerBusy ResponseError (c) 　　返回 　　} 　　ResponseSuccess (c,数据)//返回响应 　　} 　　 　　

//蓝铃/模型/params.go//ParamPostList获取帖子列表查询字符串参数 　　ParamPostList struct类型{ 　　CommunityID int64的json:“community_id”形式:“community_id”//可以为空 　　页面int64 json:“页面”形式:“页面”的例子:“1”“//页码 　　大小int64的json:“大小”形式:“大小”的例子:“10”//每页数据量 　　命令字符串的json:“秩序”形式:“秩序”的例子:“分数”//排序依据 　　} 　　 　　

//蓝铃/控制器/docs_models.go//_ResponsePostList帖子列表接口响应数据 　　_ResponsePostList struct类型{ 　　代码ResCode json:“代码”//业务响应状态码 　　消息字符串的json:“消息”//提示信息 　　[]*数据模型。ApiPostDetail json:“数据”的//数据 　　} 　　 　　

第二步:生成接口文档数据

去语言使用大摇大摆生成接口文档的方法