在 SAP 项目里写 API 文档，最容易犯的错误，是把 API Reference 当成全部。接口路径、字段名、HTTP Method、请求参数、响应结构，当然都重要，但这些内容只能回答一个很窄的问题，接口长什么样。真正做集成、做扩展、做 Fiori 应用、做外围系统对接的时候，我们更关心的是另一组问题，什么时候调用这个 API，调用之前要准备什么权限，多个 API 怎么串起来，失败后怎么补偿，哪些错误可以重试，哪些错误必须人工处理，Public Cloud 里哪些扩展方式符合 Clean Core，On-Premise 里已有增强点又该如何和新服务模型共存。
这就是 Developer Guide 和 Service Guide 存在的价值。它们不是 API Reference 的重复版，也不是把字段描述换一种说法再写一遍，而是把 API 放回真实业务和技术架构里，帮助开发团队从「知道有这个接口」走到「可以稳定、安全、可维护地使用这个接口」。
API Reference 负责精确，Developer Guide 负责把路讲清楚
API Reference 更像一份技术规格说明。它适合机器生成，也适合快速查阅。一个 OData Service 的 Entity Set、Property、Navigation Property、Filter 支持情况、响应码、错误结构，都可以放在 Reference 文档里。对 SAP Gateway Foundation、RAP Service Binding、CAP OData Service 来说，这类信息往往可以从元数据、注解、OpenAPI 定义或 API Business Hub 自
