编写 API 接口文档的重要性不言而喻，但怎么写得快、写得好却是一门学问。

为此，我整理了工作中写过的 API 接口文档，总结形成一份模板。

前置说明

• 本模板仅提供文档结构，不涉及具体的文档形式（如 doc 文档、swagger 在线文档、飞书文档等）

模板 SOP

一份 API 接口文档包括如下部分

1. 更新历史：提供版本号或发版时间维度的更新说明，具体维度选择与产品形态相关。当「更新历史」内容较多时，可单开文档并链接地址至本处
2. 使用说明：提供 API 使用前的简单说明，包括使用限制、账号注册等内容
3. 鉴权机制：提供 API 请求的鉴权机制以及整体操作流程
4. 请求结构：提供 API 的请求结构说明，包括请求地址、请求方法以及请求参数三部分内容，最后提供一个请求结构示例
5. 公共参数：提供 API 涉及的公共请求参数和返回参数
6. API 列表：提供所有 API 的说明及索引。按模块划分，并使用表格结构维护。表格每一行包含 API 名称（单开 「API 说明文档」并链接地址至本处）和说明（API 的作用）两列
7. 公共错误码：提供公共的错误码及其说明

API 说明文档 内容较多，单开文档不与 API 接口文档 放一块。可以选择模块维度或者单 API 维度编写文档，具体视接口说明复杂程度。

一个 API 说明文档 包括如下部分

• 使用场景（可选）：描述该 API 的使用场景。若有多个，以无序列表形式呈现。
• 注意事项（可选）：描述调用该 API 时需关注的注意事项，比如使用限制、请求频率等
• 请求说明：请求地址、请求方法
• 请求参数：Header/Query/Body 等说明
• 返回参数：描述返回参数结构及说明
• 示例：传入不同的参数，可能会产生不同的返回数据。此处描述几个核心链路的用例
• 错误码：仅罗列该接口业务逻辑相关的错误码，并提供 API 说明文档 的公共错误码部分的链接
• SDK 参考（可选）：若提供配套的 SDK 方便调用 API ，可在此处链接说明

具体模板

不在此文档维护，详情参考飞书文档 (opens new window)