600字范文,内容丰富有趣,生活中的好帮手!
600字范文 > 写好 API 接口文档 想清楚这几点

写好 API 接口文档 想清楚这几点

时间:2022-04-05 03:12:50

相关推荐

写好 API 接口文档 想清楚这几点

我在开始一个新的接口之前,需要进行以下判断:

请求协议是不是 HTTP、https?

请求体和响应格式是什么(XML、JSON、FormData、Raw)?

API 是不是 RESTful 风格?

如果上面三个问题的答案都清楚了,就可以开始新增一个 API 接口。

API 信息

在编辑 API 的顶部填写 API 的请求协议、方式、地址、名称;

协议支持

HTTP/HTTPS

请求方式支持

POST

GET

PUT

DELETE

HEAD

OPTIONS

PATCH

API 请求参数

设置请求头部

你可以输入或导入请求头部。

除了手动输入,你还可以批量导入请求头部,数据格式为key:value,一行一条header信息,如:

Connection: keep-aliveContent-Encoding: gzipContent-Type: application/jsonDate: Mon, 30 Dec 20:49:45 GMT

设置请求体

请求体提供了五种类型:

Form-data(表单)

Json

XML

Raw(自定义文本类型数据)

设置 Query 参数

Query 参数指的是地址栏中跟在问号?后面的参数,如以下地址中的 user_name 参数:

/user/login?user_name=jackliu

2. 批量导入的数据格式为?key=value...,通过&分隔多个参数,如:

/user/login?user_name=jackliu&user_password=hello

2. 设置 REST 参数

REST 参数指的是地址栏被斜杠/分隔的参数,如以下地址中的使用大括号包裹起来的 user_name、user_password 参数:

/user/login/{user_name}/{user_password}

WARNING 注意,你只需要在 URL 中使用 {} 将 REST 参数括起来,表单的参数名不需要填写 {}。

API响应内容

设置响应头部

你可以输入或导入响应头部。批量导入的数据格式为 key : value ,一行一条 header 信息,如:

Connection: keep-aliveContent-Encoding: gzipContent-Type: application/jsonDate: Mon, 30 Dec 20:49:45 GMT

设置响应内容

响应内容的编写方式和请求参数的类似,响应内容提供了四种类型:

Json

XML

Raw(自定义文本类型数据)

以上这个工具叫 Eoapi(现更名 Poscat),是国产的开源 API 工具,除了最常用的文档和测试功能,

目前的 v 1.9.0 版本,新增团队协作、API分享功能。除此之外他们还支持:

强大的文档功能

丰富的插件市场,可拓展

前后置脚本

支持查看所有测试历史

支持 Websocket 协议,后续也会新增支持更多的主流协议

目前在 Github 上 3.5 k star,如果你觉得这个项目还不错的话,不妨点个 star 支持一下~

Github:

/Postcatlab/postcat

Postcat 核心功能:

API文档管理:可视化 API 设计,生成 API 文档

API测试:自动生成测试参数,自动生成测试用例,可视化数据编辑

插件拓展:众多插件扩展产品功能,打造属于你和团队的 API 开发平台

Mock:根据文档自动生成 Mock,或创建自定义 Mock 满足复杂场景

团队协作:既能实现 API 分享也能可以创建云空间共同协作

Postcat 优势:

免登录即可测试:省去繁琐的验证登录的操作

界面简洁:没有冗余的功能与复杂选项

免费:中小团队以及个人使用

丰富的插件:支持数据迁移、主题、API 安全等高达 30 款插件

国产:能更好的理解国内用户的需求,与开发团队沟通无障碍

完善的用户文档:跟着操作就能快速上手

本内容不代表本网观点和政治立场,如有侵犯你的权益请联系我们处理。
网友评论
网友评论仅供其表达个人看法,并不表明网站立场。