GOFrame
框架支持全自动化的接口文档生成,保障代码与接口文档同步维护,自动生成的接口文档采用的是标准的OpenAPIv3
协议。在介绍OpenAPIv3
协议之前,建议您先阅读了解框架的规范路由特性:路由注册-规范路由 。
详细的OpenAPIv3
协议介绍请参考:https://swagger.io/specification/
接口的元数据信息可以通过为输入结构体 embedded
方式嵌入 g.Meta
结构,并通过 g.Meta
的属性标签方式来实现。
输入输出结构体中的属性的标签完整支持OpenAPIv3
协议,因此只要增加了对应的协议标签,那么生成的OpenAPIv3
接口信息中将会自动包含该属性。
大部分的标签属性已经被Server
组件自动生成,开发者需要手动设置的标签不多。常见的标签包括:
常见OpenAPIv3标签 | 说明 | 备注 |
---|---|---|
path |
结合注册时的前缀共同构成接口URI路径 | 用于g.Meta 标识接口元数据 |
tags |
接口所属的标签,用于接口分类 | 用于g.Meta 标识接口元数据 |
method |
接口的请求方式:GET/PUT/POST/DELETE...(不区分大小写) |
用于g.Meta 标识接口元数据 |
deprecated |
标记该接口废弃 | 用于g.Meta 标识接口元数据 |
summary |
接口/参数概要描述 | 缩写sm |
description |
接口/参数详细描述 | 缩写dc |
in |
参数的提交方式 | header/path/query/cookie |
default |
参数的默认值 | 缩写d |
mime |
接口的MIME 类型,例如multipart/form-data 一般是全局设置,默认为 。 |
用于g.Meta 标识接口元数据 |
type |
参数的类型,一般不需要设置,特殊参数需要手动设置,例如file |
仅用于参数属性 |
核心的接口信息已经自动生成,如果开发者想要更进一步完善接口信息,可以通过s.GetOpenApi()
接口获取到OpenAPIv3
的结构体对象,并手动填充对应的属性内容即可。我们来看一个示例,在该示例中,我们将接口中的标签进行了自定义的排序,并且增加了对每个标签的详细描述:
我们可以发现通过通用的OpenAPIv3
对象我们可以自定义修改其内容,并且根据它生成其他各种自定义类型的接口文档。
*ghttp.UploadFile
type
为file
类型
网站栏目:创新互联GoFrame教程:GoFrameWEB服务开发-接口文档
文章分享:http://www.shufengxianlan.com/qtweb/news1/358851.html
网站建设、网络推广公司-创新互联,是专注品牌与效果的网站制作,网络营销seo公司;服务项目有等
声明:本网站发布的内容(图片、视频和文字)以用户投稿、用户转载内容为主,如果涉及侵权请尽快告知,我们将会在第一时间删除。文章观点不代表本网站立场,如需处理请联系客服。电话:028-86922220;邮箱:631063699@qq.com。内容未经允许不得转载,或转载时需注明来源: 创新互联