研发平台接口文档要能被前端、后端、测试和运维直接使用，关键是把接口信息拆成“接口清单总表”和“单接口详情表”两层：总表管全局，详情表管单个接口。本文提供两张可直接复制填写的空白表，并逐字段说明填写口径、必填与选填规则，再用一个查询接口的完整示例演示填写过程，最后给出接口变更后的维护方法。
要点总览（TL;DR）
- 模板由两张表组成：接口清单总表登记接口名称、编号、方向、协议、鉴权方式、负责人和状态；单接口详情表逐项填写请求地址、方法、参数、返回字段、错误码、限流与变更记录。
- 必填项以“缺失后调用方无法对接或无法判断接口是否可用”为标准：总表除详情表位置外均为必填，详情表的编号、名称、说明、请求地址、方法、参数、返回字段和错误码为必填。
- 填写顺序固定为先总表后详情表，总表一行对应详情表一份，通过接口编号和详情表位置建立索引，评审时按编号抽查核对。
- 接口变更时按破坏性变更与兼容变更分别处理，删除字段先标记废弃，变更记录按时间倒序保留版本、影响范围和生效时间。
- 文档承载可与需求、任务关联，ONES 文档功能可用于存放总表与详情表并留下评审过程；接口少、调用方单一时共享表格配合固定评审节奏同样可行。
可复制空白模板：接口清单总表与单接口详情表
模板由两张表组成，填写顺序是先总表、后详情表。总表用于登记研发平台对外或内部提供的全部接口，形成一份可检索的接口目录；详情表针对每一个需要被调用方使用的接口单独填写一份。先填总表可以确定接口范围和负责人，再逐个展开详情，避免遗漏或重复。
接口清单总表（空白）
| 接口名称 | 接口编号 | 方向 | 协议 | 鉴权方式 | 负责人 | 状态 | 详情表位置 |
|---|---|---|---|---|---|---|---|
单接口详情表（空白）
| 字段 | 填写内容 |
|---|---|
| 接口编号 | |
| 接口名称 | |
| 接口说明 | |
| 请求地址 | |
| 请求方法 | |
| 请求头 | |
| 请求参数 | |
| 返回字段 | |
| 错误码 | |
| 限流与超时 | |
| 调用示例 | |
| 变更记录 |
使用顺序建议固定为三步：第一步在总表登记接口编号、名称、方向、协议、鉴权方式、负责人和状态；第二步按总表每一行新建一份详情表，填写请求与返回细节；第三步把详情表位置回填到总表，形成总表到详情表的索引。总表一行对应详情表一份，这个对应关系是后续维护和评审的基础。
字段说明：每个字段记录什么、怎么填
字段说明的作用是统一填写口径，让不同负责人写出的接口文档结构一致。总表字段偏管理属性，详情表字段偏技术契约，两者通过接口编号关联。
总表字段含义
| 字段 | 记录内容 | 填写口径 |
|---|---|---|
| 接口名称 | 接口的业务名称 | 用调用方能理解的业务语言命名，如“查询项目列表”，避免只写内部代号 |
| 接口编号 | 接口的唯一标识 | 全表唯一，建议采用“模块前缀＋序号”，详情表沿用同一编号 |
| 方向 | 接口的调用方向 | 标明研发平台提供、研发平台调用或双向同步 |
| 协议 | 通信协议类型 | 填写实际使用的协议，如HTTP、RPC、消息队列等 |
| 鉴权方式 | 调用方的身份校验方式 | 写明令牌、签名、证书或网关统一鉴权等具体方式 |
| 负责人 | 接口的责任人 | 填写能对接口契约和变更负责的个人，不写部门统称 |
| 状态 | 接口当前生命周期状态 | 使用统一取值，如设计中、联调中、已上线、已下线 |
| 详情表位置 | 详情表的存放位置 | 填写文档链接或文档标题，保证从总表可直接定位 |
详情表字段含义
| 字段 | 记录内容 | 填写口径 |
|---|---|---|
| 接口编号 | 与总表一致的唯一标识 | 直接复制总表编号，不另行编号 |
| 接口名称 | 与总表一致的业务名称 | 与总表保持同一名称，便于双向检索 |
| 接口说明 | 接口用途与适用场景 | 说明解决什么问题、由谁调用、返回结果用于什么 |
| 请求地址 | 接口的访问路径 | 写完整路径，区分环境时分别列出 |
| 请求方法 | 调用的操作类型 | 按协议填写，如GET、POST等 |
| 请求头 | 调用需携带的头部信息 | 列出字段名、是否必填和用途，鉴权信息在此说明 |
| 请求参数 | 入参清单 | 逐项列出参数名、类型、是否必填、说明和示例值 |
| 返回字段 | 出参清单 | 逐项列出字段名、类型、说明，嵌套结构标明层级 |
| 错误码 | 失败情况的返回约定 | 列出错误码、含义和处理建议 |
| 限流与超时 | 调用约束 | 写明调用频率上限、超时时间和重试建议 |
| 调用示例 | 可运行的请求与返回样例 | 给出一次完整请求和对应返回，字段与参数表一致 |
| 变更记录 | 接口契约的修改历史 | 按时间倒序记录版本、修改内容和影响范围 |
两张表的对应关系体现在三个位置：接口编号在两表中完全一致；接口名称在两表中保持同一写法；总表的“详情表位置”指向详情表所在文档。评审时可以先抽查总表若干行，再按编号找到详情表，核对名称、参数和状态是否一致。
必填与选填：哪些字段缺失会导致文档不可用
必填项的判断标准是：缺失后调用方无法完成对接，或无法判断接口是否可用。选填项用于补充说明，缺失不影响基本对接，但会影响排障效率。
| 表 | 必填字段 | 选填字段 |
|---|---|---|
| 接口清单总表 | 接口名称、接口编号、方向、协议、鉴权方式、负责人、状态 | 详情表位置（详情表尚未建立时可暂空） |
| 单接口详情表 | 接口编号、接口名称、接口说明、请求地址、请求方法、请求参数、返回字段、错误码 | 请求头、限流与超时、调用示例、变更记录 |
必填字段缺失的后果按字段区分：缺少请求地址、请求方法或参数定义，调用方无法发起请求；缺少返回字段和错误码，调用方无法处理结果和异常；缺少鉴权方式，联调阶段会反复确认身份校验；缺少负责人，接口变更时无人确认影响范围。选填字段缺失通常不阻断对接，但请求头缺失可能导致鉴权失败排查变慢，限流与超时缺失会让调用方在高并发场景下缺少预期。
补填时机建议与接口生命周期绑定：设计阶段补齐总表必填项和详情表的请求、返回定义；联调前补齐请求头、调用示例和错误码；上线前补齐限流与超时；每次变更后立即更新变更记录。状态为“已上线”的接口，必填项应全部完整，否则应在总表状态中标注待补，避免调用方误用。
填写示例：一个查询接口的完整填写
以下示例为演示情景，用于说明填写方式，不对应任何具体平台的真实接口。示例中的接口用于按项目编号查询项目基本信息。
总表示例（一行）
| 接口名称 | 接口编号 | 方向 | 协议 | 鉴权方式 | 负责人 | 状态 | 详情表位置 |
|---|---|---|---|---|---|---|---|
| 查询项目基本信息 | PROJ-001 | 研发平台提供 | HTTP | 请求头令牌校验 | 张工 | 已上线 | 《PROJ-001 查询项目基本信息》 |
详情表示例
| 字段 | 填写内容 |
|---|---|
| 接口编号 | PROJ-001 |
| 接口名称 | 查询项目基本信息 |
| 接口说明 | 按项目编号查询项目名称、负责人和状态，供外部系统展示项目概况 |
| 请求地址 | /api/v1/projects/{projectId} |
| 请求方法 | GET |
| 请求头 | Authorization：必填，携带访问令牌；Content-Type：选填，固定为application/json |
| 请求参数 | projectId：字符串，必填，路径参数，项目唯一编号，示例“P2024001” |
| 返回字段 | projectId：字符串，项目编号；projectName：字符串，项目名称；owner：字符串，负责人；status：字符串，项目状态；updatedAt：字符串，最后更新时间 |
| 错误码 | 401：令牌无效，需重新获取；404：项目不存在，核对projectId；429：调用频率超限，降低频率后重试；500：服务异常，联系负责人 |
| 限流与超时 | 单账号每分钟不超过60次；超时时间3秒；超时后建议重试1次 |
| 调用示例 | 请求：GET /api/v1/projects/P2024001，请求头携带令牌；返回：{“projectId”:”P2024001″,”projectName”:”示例项目”,”owner”:”张工”,”status”:”进行中”,”updatedAt”:”2024-06-01 10:00:00″} |
| 变更记录 | v1.0 首次发布；v1.1 返回字段新增updatedAt，旧字段保持不变 |
对照字段说明检查这份示例：总表的接口编号、名称与详情表一致；详情表的请求参数、返回字段与调用示例中的字段一一对应；错误码覆盖了鉴权失败、资源不存在、限流和服务异常四类常见情况；变更记录写明了版本和影响范围。按同样方式填写其他接口，即可保持整套文档口径统一。
调整与维护方法：接口变更后如何更新文档
接口文档的价值取决于它与实际接口的一致程度。研发平台的接口会随需求迭代增删字段、调整参数或下线旧版本，文档需要一套固定的调整和维护规则。
字段增删的调整原则
- 新增字段先判断是否影响调用方：新增必填请求参数属于破坏性变更，需要通知调用方并约定切换时间；新增返回字段通常向后兼容，但仍要写入返回字段表和变更记录。
- 删除字段前先在文档中标记废弃，保留说明和替代字段，待调用方完成迁移后再从模板中移除。
- 字段改名时同步修改总表名称、详情表参数表和调用示例，三处保持一致，避免只改一处造成口径分裂。
- 模板本身增删字段时，在模板说明中记录调整原因，已填写的详情表按新模板补齐，不保留两套并行结构。
变更记录与版本维护
每个接口的详情表保留变更记录，按时间倒序记录版本号、修改内容、影响范围和生效时间。总表状态随接口生命周期更新：设计中的接口标注为设计中，联调完成后改为已上线，下线接口保留记录并标注已下线，不直接删除总表行，便于调用方追溯。涉及多个接口的公共调整，例如统一鉴权方式或统一错误码规范，可先在总表层面记录一次，再逐个更新详情表。
评审与交接检查
接口文档在发布前和负责人交接时各做一次检查。评审检查可以按以下清单执行：
- 总表每一行的必填字段是否完整，状态是否与实际进度一致。
- 总表每一行是否都能通过“详情表位置”找到对应详情表，编号和名称是否一致。
- 详情表的请求参数、返回字段与调用示例是否对应，错误码是否覆盖主要失败场景。
- 本次变更是否写入变更记录，影响范围是否已通知调用方。
- 负责人交接时，新负责人是否确认了接口现状、待办变更和调用方清单。
当接口数量增多、参与方涉及产品、开发和测试多个角色时，文档的承载和流转也需要管理。ONES 的文档功能可用于存放接口清单总表和详情表，把文档与对应的需求、任务关联起来，接口变更时通过任务状态和评审记录留下过程信息，让负责人和调用方在同一处确认变更范围。是否采用这种方式取决于团队的协作习惯；接口数量少、调用方单一时，用共享表格配合固定评审节奏同样可以维持文档一致性。
常见问题
接口文档模板里的“详情表位置”在详情表还没建好时怎么填？
详情表尚未建立时，该字段可以暂空，但总表其余必填项应先填完整。建议在总表状态中标注“详情表待建”，等详情表建立后立即回填文档链接或文档标题。状态为“已上线”的接口，该字段应补齐，否则调用方无法从总表定位到具体契约。
新增一个返回字段，需要通知所有调用方吗？
新增返回字段通常向后兼容，调用方不处理该字段也能正常解析，但仍应写入返回字段表和变更记录，并在版本说明中标注生效时间。如果新增的是必填请求参数，则属于破坏性变更，需要提前通知调用方并约定切换时间，避免联调或线上调用失败。
接口下线后，总表里的记录可以直接删除吗？
不建议直接删除。总表行保留并标注“已下线”，详情表保留变更记录和下线时间，便于调用方追溯历史契约和排查旧调用。确认无调用方依赖后，可在文档归档区集中存放，而不是从接口目录中抹去记录。
多个接口统一调整鉴权方式，文档怎么改效率更高？
先在总表层面记录一次公共调整，说明调整原因、生效时间和影响范围，再逐个更新详情表的请求头字段和调用示例。更新完成后按总表逐行核对鉴权方式是否一致，避免部分接口遗漏。涉及调用方切换的，提前发出通知并约定过渡期。
接口文档放在共享表格里和放在文档工具里，怎么选？
接口数量少、调用方单一、变更频率低时，共享表格配合固定的评审节奏即可维持一致性。接口数量增多、参与方涉及产品、开发和测试多个角色时，可考虑用文档工具承载，把文档与需求、任务关联，变更时通过任务状态和评审记录留下过程信息。ONES 的文档功能可用于存放接口清单总表和详情表，并与对应需求、任务关联；是否采用取决于团队协作习惯。
