想做具身机器人 OpenAPI 二次开发这 5 条对接文档设计必须撕开最近帮一位做具身机器人二次开发的客户做对接支持对方工程师感慨“接口字段定义能看懂但放到实际业务场景里不知道该怎么用。” 这也是今天想重点聊聊的话题。我们的 OpenAPI 对接文档经历过一次完整迭代V1.0 → V1.1。并不是底层接口技术升级只是撰写文档的思路完全换了。V1.0 那个 “工程师视角” 的版本V1.0 版本的对接文档当时是按照技术清单思路写的 罗列全部接口路径 罗列所有入参、返回字段 附带基础请求 / 响应示例 整理基础错误码看上去要素齐全。客户对接后反馈依然集中“字段看得懂放到业务场景里不知道怎么落地使用。”还有更实际的疑问“正常成功调用的逻辑写得很清楚异常场景怎么处理token 校验失败怎么办必填字段缺失怎么排查重复提交如何避免重复执行”V1.0 本质只是一份接口清单并不是能指导客户落地的操作手册。行业里典型的反思和几位做 B 端平台的同行交流对接文档的演进路径大多相似V1.0 阶段工程师视角罗列系统具备哪些能力V1.1 阶段客户视角讲清楚使用者该如何调用V2.0 阶段业务视角按照使用者的真实业务场景组织文档内容听着简单但每切换一次视角文档几乎都要重构不是简单增删文字。V1.1 的关键改动不聊底层接口字段调整只说文档设计思路上的核心优化每个接口配套对应的业务场景说明—— 明确这个接口可以解决哪一类业务问题字段标注必填 / 可选补充业务释义—— 开发者快速区分哪些参数不可省略每个接口同时提供成功 异常调用示例覆盖鉴权失败、参数缺失、幂等冲突等常见问题单独明确幂等机制—— 说明重复提交请求时平台识别与处理逻辑清晰说明鉴权机制Token 类型、传递方式、Header 规范完善异常码对照表方便开发者基于返回码做程序侧的容错处理一个反常识的细节写对接文档时幂等与鉴权逻辑最容易被遗漏。工程师写文档习惯优先描述 “接口正常调用流程”。但对接方工程师更关心 “调用报错后如何定位问题”这刚好对应了成功路径和失败路径两套逻辑。我们内部定下规范每个接口都必须包含两部分内容成功路径标准调用流程与预期结果失败路径列举常见报错场景、排查思路、平台幂等防护逻辑还有一件事文档不是 “写完就归档”V1.1 落地之后我们建立了一条开发规范接口变更先更新文档再修改代码。这个做法看着反常规但带来几个很实在的收益 文档始终保持最新状态 文档描述能力和线上实际接口保持一致 内部开发人员以文档为基准实现减少理解偏差先文档后代码这套流程实实在在降低了双方对接沟通成本提升整体对接效率。写在最后对接文档这件事不只是单纯的文字整理也是产品能力的一环。合作方评估技术团队是否靠谱对接文档就是最直观的参考。文档逻辑清晰会让人觉得团队专业文档含糊不清很容易让人怀疑团队对自身系统的理解程度。现在我们给新同事做技术培训第一课不是上手写代码而是学习如何编写对接文档。对接文档是外部开发者能直接接触到的产品说明书也是技术能力对外的直观体现。对接文档不只是单纯的技术文本输出更是站在使用者视角的产品能力输出。关于作者专注具身智能与工业 AI 视觉落地深耕机器人 OpenAPI 二次开发适配覆盖多款主流人形机器人平台可提供视觉算法、硬件联调、产线实机部署相关技术落地服务。