接口文档规范.md 7.4 KB

接口文档规范

前言

众所周知,拥有 API 的应用程序项目,接口文档属于研发完整交付的一部分。生态上流行的接口文档工具数不胜数,其中有 Swaggerapidoc 等。为了提高研发效力与交付速度,离不开工具利器,也就是说、接口文档的使用工具赋能,提高能效。

除此能效之外,还有团队统一工具的作用。

规范

开发 API 接口时,必须要编写或生成接口的文档。

一个基本的接口文档,至少需要包含以下的内容:

  • 接口说明:包括接口功能描述、接口地址、请求头要求、请求方式
  • 请求示例
  • 请求参数说明:包括字段名称、字段说明、字段类型、是否必填、字段示例
  • 响应示例
  • 响应参数说明:包括包括字段名称、字段说明、字段类型、是否必定有值、字段示例

工具

目前所有接口文档统一使用基于 eolinker 的 API 管理系统 管理 API。

但由于 eolinker 该版本不支持代码自动生成接口文档,并且由于之前遗留的历史包袱,部分接口的分组和信息不是很完善。

目前管理后台和 wapapi 已有部分接口尝试使用 Swagger,不过还没正式部署。

Swagger

TODO

eolinker

eolinker 的 API 文档不支持自动生成,需要手动编写。

创建项目

进入API开发管理页面,点击新建项目按钮,在弹框中输入项目名称等信息并点击确定保存即可。

API 列表简介

API 列表中展示了丰富的 API 信息:

APIsURL创建者最近更新者更新日期其他操作
星标API 名称URLAPI 创建人API 最后修改人API 更新日期新窗口打开、修改、删除

  • 切换 API 列表显示模式

API 列表提供了两种显示模式:

  1. 详细模式:会在列表中显示详细的信息;
  2. 省略模式:仅会显示 API 的基础信息(API 名称、URL)。
  • 点击列表右上方的 详细 / 省略 按钮,切换合适的显示模式:

  • API 列表排序 & 筛选

点击列表右上方的 排序 / 筛选 按钮,设置排序或筛选条件:

创建 API

  • API 基本信息

进入 API 文档 页面,点击 新建 API 按钮,进入到 API 编辑 页面。

  • 设置 API 分组

最多支持三级分组,对 API 进行适当的归类有助于提高管理效率。

  • 设置 API URL 以及 API 名称

如果有多个项目环境,不同的项目环境拥有不同的请求 URL 前缀,那么 URL 仅需要填写 API 的路径即可(如 / user/login),切换不同的 URL 前缀可以使用 eoLinker AMS 中的环境管理功能。相关教程请前往 API 开发管理 > 公共资源管理 > 环境管理 一节。 设置 API 状态

在 eoLinker AMS 中,API 拥有以下的几种状态:

状态描述
启用当前 API 正常使用
维护当前 API 正在维护,不建议使用
弃用当前 API 已经停用,不建议使用
待定当前 API 尚未开发,需求待定
开发当前 API 正在开发
测试当前 API 正在测试
对接当前 API 正在对接调试
BUG当前 API 出现 BUG,建议尽快修复
  • 请求信息

在 API 文档中,可以记录 Header、Request Body、REST Params、Query/GET Params、鉴权等信息。

  • 设置 Header

请求头部中,可以手动输入接口的头部信息,也可以使用 导入头部 的功能批量导入:

  • 设置 Request Body

Body 请求参数提供了两种类型:Form-data 或者 Raw。可以手动输入请求参数或者使用 导入 JSON / 导入 XML 功能来批量导入请求参数。

同时,Form-data 支持记录无限层级结构的请求参数,参数层级通过 “>>” 表示并且能对每个参数设定非常详细的示例和值可能性等:

  • 设置 REST Params

在 eoLinker AMS 中,REST 参数在 URL 中使用 {param_name} 表示,如 /user/login/{user_name}/{user_type},该 API 拥有 REST 参数 user_name 和 user_type。

注意,只需要在 URL 中使用 {} 将 REST 参数括起来,下方的表格中不需要使用{}。

  • 返回参数

可以手动输入请求参数或者使用 导入 JSON / 导入 XML 功能来批量导入请求参数。

  • 返回示例

可以记录 API 请求成功或失败的示例,eoLinker AMS 提供了 API 来获取编写好的 API 返回示例,可以用于前端开发人员测试 API。

保存 API 文档之后,通过返回示例 API 即可获得事先编写好的返回示例:

  • API 详细文档

当 API 文档无法详细地记录下 API 信息时,可以通过使用 Markdown 或者富文本的方式来编写需要补充的信息:

管理 API

  • 修改 API

进入 API 详情 页,点击 编辑 按钮即可进入 API 编辑页面:

  • 删除 API

删除单个 API

进入 API 列表 页面,点击接口的 删除 按钮;或者进入 API 详情 页,点击上方 其他操作 中的 修改 按钮。

以此方法删除的接口会进入 API 回收站,并不会直接删除,可以在 API 回收站中找回误删的 API。

批量删除 API

进入 API 列表 页面,点击 批量操作 按钮,选择需要删除的 API 之后,点击 移入回收站 按钮即可:

  • API 回收站

恢复 API

进入 API 回收站 页面,选择需要恢复的 API,点击 恢复 按钮或者进行批量恢复即可。

彻底删除 API

进入 API 回收站 页面,选择需要删除的 API,点击 彻底删除 按钮或者进行批量删除即可。