阅读(2044)
赞(13)
GoFrame WEB服务开发-接口文档
2022-04-12 11:16:08 更新
GoFrame框架支持全自动化的接口文档生成，保障代码与接口文档同步维护，自动生成的接口文档采用的是标准的OpenAPIv3协议。在介绍OpenAPIv3协议之前，建议您先阅读了解框架的规范路由特性：路由注册-规范路由 。
一、OpenAPIv3
详细的OpenAPIv3协议介绍请参考：https://swagger.io/specification/
二、g.Meta元数据
接口的元数据信息可以通过为输入结构体 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
|
仅用于参数属性 |
四、扩展OpenAPIv3信息
核心的接口信息已经自动生成，如果开发者想要更进一步完善接口信息，可以通过s.GetOpenApi()接口获取到OpenAPIv3的结构体对象，并手动填充对应的属性内容即可。我们来看一个示例，在该示例中，我们将接口中的标签进行了自定义的排序，并且增加了对每个标签的详细描述：
我们可以发现通过通用的OpenAPIv3对象我们可以自定义修改其内容，并且根据它生成其他各种自定义类型的接口文档。
五、常见问题
1、如何实现文件上传的接口定义？
- 参数接收的数据类型使用
*ghttp.UploadFile - 如果需要接口文档也支持文件类型，那么参数的标签中设置
type为file类型
