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

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

1. 请求协议是不是 HTTP、https?

2. 请求体和响应格式是什么（XML、JSON、FormData、Raw）?

3. API 是不是 RESTful 风格？

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

API 信息

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

协议支持

• HTTP/HTTPS

请求方式支持

• POST

• GET

• PUT

• DELETE

• HEAD

• OPTIONS

• PATCH

API 请求参数

设置请求头部

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

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

Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

 

设置请求体

请求体提供了五种类型：

1. Form-data（表单）

2. Json

3. XML

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

1. 设置 Query 参数

1. Query 参数指的是地址栏中跟在问号？后面的参数，如以下地址中的 user_name 参数：

/user/login?user_name=jackliu

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

api.eolinker.com/user/login?user_name=jackliu&user_password=hello

     2. 设置 REST 参数

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

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

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

API响应内容

设置响应头部

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

Connection: keep-alive

Content-Encoding: gzip

Content-Type: application/json

Date: Mon, 30 Dec 2019 20:49:45 GMT

设置响应内容

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

1. Json

2. XML

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

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

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

• 强大的文档功能

• 丰富的插件市场，可拓展

• 前后置脚本

• 支持查看所有测试历史

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

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

Github：

https://github.com/Postcatlab/postcat

Postcat 核心功能：

• API 文档管理：可视化 API 设计，生成 API 文档

• API 测试：自动生成测试参数，自动生成测试用例，可视化数据编辑

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

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

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

Postcat 优势：

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

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

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

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

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

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