team-standard/接口文档规范.md

接口文档规范

前言

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

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

规范

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

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

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

工具

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

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

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

Swagger

TODO

eolinker

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

创建项目

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

API 列表简介

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

★	APIs	URL	创建者	最近更新者	更新日期	其他操作
星标	API 名称	URL	API 创建人	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，点击 彻底删除 按钮或者进行批量删除即可。