网站信息可以边建设边组织,wordpress 字体 插件下载,免费空间大的云盘,国内wordpress博客想要使用gin-swagger为你的代码自动生成接口文档#xff0c;一般需要下面三个步骤#xff1a;
按照swagger要求给接口代码添加声明式注释#xff0c;具体参照声明式注释格式。使用swag工具扫描代码自动生成API接口文档数据使用gin-swagger渲染在线接口文档页面
第一步一般需要下面三个步骤
按照swagger要求给接口代码添加声明式注释具体参照声明式注释格式。使用swag工具扫描代码自动生成API接口文档数据使用gin-swagger渲染在线接口文档页面
第一步添加注释
在程序入口main函数上以注释的方式写下项目相关介绍信息。
package main// title 这里写标题
// version 1.0
// description 这里写描述信息
// termsOfService http://swagger.io/terms/// contact.name 这里写联系人信息
// contact.url http://www.swagger.io/support
// contact.email supportswagger.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层按如下方式写上注释
// 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?page1size10ordertime// 初始化结构体时指定初始参数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)// 返回响应
}上面注释中参数类型使用了objectmodels.ParamPostList具体定义如下
// 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。
// bluebell/controller/docs_models.go// _ResponsePostList 帖子列表接口响应数据
type _ResponsePostList struct {Code ResCode json:code // 业务响应状态码Message string json:message // 提示信息Data []*models.ApiPostDetail json:data // 数据
}第二步生成接口文档数据
编写完注释后使用以下命令安装swag工具
go get -u github.com/swaggo/swag/cmd/swag在项目根目录执行以下命令使用swag工具生成接口文档数据。
swag init执行完上述命令后如果你写的注释格式没问题此时你的项目根目录下会多出一个docs文件夹。
./docs
├── docs.go
├── swagger.json
└── swagger.yaml第三步引入gin-swagger渲染文档数据
然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容 import (// liwenzhou.com ..._ bluebell/docs // 千万不要忘了导入把你上一步生成的docsgs github.com/swaggo/gin-swaggergithub.com/swaggo/gin-swagger/swaggerFilesgithub.com/gin-gonic/gin
)注册swagger api相关路由
r.GET(/swagger/*any, gs.WrapHandler(swaggerFiles.Handler))把你的项目程序运行起来打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文档了。 gin-swagger同时还提供了DisablingWrapHandler函数方便我们通过设置某些环境变量来禁用Swagger。例如
r.GET(/swagger/*any, gs.DisablingWrapHandler(swaggerFiles.Handler, NAME_OF_ENV_VARIABLE))此时如果将环境变量NAME_OF_ENV_VARIABLE设置为任意值则/swagger/*any将返回404响应就像未指定路由时一样。 参考文章
https://www.fansimao.com/937539.html
