API 文档与入口梳理
接口相关的工作从入口梳理开始：公开的开发者文档、开放平台页面、SDK 与示例代码都能反映接口的端点、参数与认证方式。文档完善时它是最省力的清单来源；文档缺失时则要转向业务页面观察与前端资源分析。需要强调的是，文档描述与实际行为常有出入，验证必须以实际请求为准。
基本信息
| 来源 | 开发者文档、开放平台、SDK 与示例代码 |
|---|---|
| 整理字段 | 端点、方法、认证方式、参数、文档来源 |
| 文档缺失时 | 以业务页面观察与前端资源分析为主 |
| 边界 | 只整理授权范围内的接口 |
| 记录要求 | 标注文档版本或访问时间 |
典型使用场景
- 从开发者文档整理完整的接口入口清单
- 从开放平台页面识别面向第三方的接口与凭据类型
- 从 SDK 代码提取接口路径、参数名与签名方式
- 文档缺失时通过业务页面操作与抓包反推接口
- 为接口类测试排期提供端点与认证状态依据
清单字段示例
清单字段示例
# 端点：/api/v2/orders
# 方法：GET 与 POST
# 认证：会话 Cookie 或 Bearer 令牌
# 参数：page、size、status（查询类）
# 文档来源：官方开发者页（访问日期记录在清单表头）来源可靠度读法
| 来源 | 可靠度 | 核实方式 |
|---|---|---|
| 开发者文档 | 中，可能滞后于实现 | 实际请求验证参数与返回 |
| SDK 代码 | 高，与实现强相关 | 核对版本号与调用示例 |
| 开放平台页面 | 中，含商务与权限说明 | 核对凭据类型与授权流程 |
| 页面与抓包反推 | 高，反映当前实现 | 覆盖多模块，避免样本偏差 |
公开文档与实际行为可能有出入：文档用于建立清单，结论必须以实际验证为准。
接口文档中标注为废弃的端点值得留意：往往仍可访问，且维护与鉴权投入更少。
清单维护要点
- 每条接口同时记录文档来源与实测日期，出现差异时以实测为准
- 标注认证方式与所需角色，便于安排测试账号
- 把公开文档与实际请求的差异单独汇总，作为配置类问题线索
- 接口清单与参数清单分开维护，通过接口标识关联
- 复测时按同一清单逐项核对，避免覆盖度漂移