【 Apifox】Apifox接口设计
2023-03-31 10:36:45 时间
Apifox官网地址:http://apifox.cn/a103abcc
文章目录
一、接口设计 (接口文档)
接口设计即定义接口文档规范(如接口路径、参数、返回值、数据结构等)。
接下来手把手带你进行接口设计。
二、如何定义接口?
- 点击左侧搜索框旁边的 + 号按钮即可打开新建窗口,也可使用 快捷键 Ctrl(⌘) + N。
- 在打开的窗口中,直接定义接口相关信息。
三、接口路径
以斜杠/起始的接口 path 部分,如/pets
、/pets/{id}
。
注意:
- 接口路径 建议不要包含 HTTP 协议及域名,这部分建议在 环境管理 的前置URL里设置,接口调试时的 URL 会自动加上当前环境的前置URL。
- 特殊情况需在接口路径要带上HTTP 协议及域名的,系统也能支持,但不建议这么做。接口调试时,系统如检测到接口路径是以http://或https://起始的,会自动忽略当前环境里前置 URL。
- Apifox 中的 Path 参数是以大括号包裹起来表示,而非冒号起始表示。正确示例:/pets/{id},错误示例/pets/:id。
- 接口路径 不可包含Query 参数(即 URL 中 ?后的参数),Query 参数在下方请求参数部分填写。
四、基础信息
这部分比较简单,一看就懂,不再赘述。
五、请求参数
1.Params 参数
包含 Query 参数和 Path 参数两部分。
- Query 参数:即 URL 中 ?后的参数。
- Path 参数:自动提取接口路径中大括号包裹起来的参数,如/pets/{id}中的的{id}即表示名为id的 Path 参数。
2.Body 参数
3.Body 参数类型
- none:无 body 参数。
- form-data:即 Content-Type为
multipart/form-data
。 - x-www-form-urlencoded:即 Content-Type 为
application/x-www-form-urlencoded
。 - json:即 Content-Type 为
application/json
。 - xml:即 Content-Type 为
application/xml
。 - binary:发送文件类数据时使用。
- raw:发送其他文本类数据时使用。
注意:
- Body 参数类型为json或xml时,需要设置数据结构,并且数据结构可以引用数据模型,详细说明请查看文档:数据结构/数据模型。
- 接口发送请求的时候会根据Body 参数类型自动在请求Header加上对应的Content-Type,无需手动设置。
- 若需要手动设置Header中的Content-Type,则其值必须和Body 参数类型相匹配,否则系统会自动忽略掉手动设置的Content-Type。
示例:
- 如 Body 参数类型为form-data,手动设置Content-Type的值为multipart/form-data;charset=GBK是有效的;但如果把值设置为application/json则会被系统忽略掉,因为和参数类型不匹配。
- Body参数类型为raw时,手动设置Content-Type的值不受限制。
六、参数中使用环境变量(或全局变量/临时变量)
所有参数都可以使用变量,使用方式为双大括号包裹变量名,如{{my_variable}}
,表示引用名为my_variable
的变量。
参数值使用变量时可以包含变量以外的字符串,如:参数值设置为prefix-{{my_variable}}-surfix
,假设运行时变量my_variable
的值为123,则实际请求时参数的值为prefix-123-surfix
。
七、返回响应
返回响应定义主要包含以下几部分:
- 接口返回的 HTTP 状态码
- 返回内容的数据格式:JSON、XML、HTML、Raw、Binary
- 数据结构:仅JSON、XML可配置数据结构。
注意:
- 当一个接口在不同情况下会返回不同数据结构时,可设置多个返回响应。点击返回响应模块右上方的+ 新建即可添加。
- 定义好数据结构后,接口调试时,系统会自动校验返回的数据是否符合定义的数据结构,非常方便,更多说明请查看文档:接口调试/接口用例。
- 定义好数据结构后,使用 mock 功能时,系统会自动根据定义的数据结构 mock 出非常人性化的数据,非常方便,更多说明请查看文档:Mock 数据
八、公共响应
公共响应主要用来实现返回响应的复用。
通常不同接口在某些情况下会返回相同的数据结构,如资源不存在(404)、没有访问权限(401)等,这些建议设置为公共响应,避免重复编写,方便统一管理。
设置方法:打开项目设置->公共响应,在这里管理公共响应。
九、响应示例
设置返回响应的示例数据,方便查阅接口文档的人快速了解数据结构。
返回 Response 的示例数据也可以设置多次,点击响应示例模块右上方的+ 新建即可添加。建议至少设置两个示例:成功示例、失败示例。
十、其他
1.OperationID
支持设置 OperationId属性,导出OpenAPI格式时会将此处的值导出到 Operation 对象的 OperationId 里
结语
为了方便大家,我将Apifox的链接放下面,大家直接点击就可以进入;
Apifox网址:http://apifox.cn/a103abcc
相关文章
- 从本体论开始说起——运营商关系图谱的构建及应用
- 如何成为一名数据科学家?
- 从未见过的堂兄杀了人,你的DNA是关键证据
- 20个安全可靠的免费数据源,各领域数据任你挑
- 20个安全可靠的免费数据源,各领域数据任你挑
- 阿里云李飞飞:All in Cloud时代,云原生数据库优势明显
- 基于Hadoop生态系统的一高性能数据存储格式CarbonData(性能篇)
- 大数据告诉你:10年漫威,到底有多少角色
- TigerGraph:实时图数据库助力金融风控升级
- Splunk利用Splunk Connected Experiences和Splunk Business Flow 扩大数据访问
- 大数据开发常见的9种数据分析手段
- 以免在景区看人,我爬了5W条全国景点门票数据...
- 【实战解析】基于HBase的大数据存储在京东的应用场景
- 数据科学家告诉你哪些计算机科学书籍是你应该看的
- Kafka作为大数据的核心技术,你了解多少?
- Spring Boot 整合 Redis 实现缓存操作
- 大数据学习必须掌握的五大核心技术有哪些?
- 基于Antlr在Apache Flink中实现监控规则DSL化的探索实践
- 甲骨文再次被Gartner评为分析型数据管理解决方案魔力象限领导者
- 爬取吴亦凡微博102118条转发数据,扒一扒流量的真假