关于api:写好-API-接口文档想清楚这几点

31次阅读

共计 1305 个字符,预计需要花费 4 分钟才能阅读完成。

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

  • 申请协定是不是 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-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

设置申请体申请体提供了五种类型:

  • Form-data(表单)
  • Json
  • XML
  • Raw(自定义文本类型数据)

设置 Query 参数

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

/user/login?user_name=jackliu

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

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

设置 REST 参数

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

/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

设置响应内容

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

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

以上这个工具叫 Eoapi,是 国产的开源 API 工具,除了最罕用的文档和测试性能。

目前的 v 1.9.0 版本,新增 API 分享、团队合作性能。除此之外他们还反对:弱小的文档功能丰富的插件市场,可拓展前后置脚本反对查看所有测试历史反对 Websocket 协定,后续也会新增反对更多的支流协定

在线 Demo:

https://www.eoapi.io/?utm_sou…

如果你感觉这个开源我的项目还能够的话,无妨点个 star 反对下他们,如果你感觉还须要持续优化,无妨去提个 Issue.

Github:
https://github.com/eolinker/e…

Gitee:
https://gitee.com/eolink_admi…

正文完
 0