REST API 概览文档怎么写，写给 SAP ABAP 与企业集成项目的一套实战模板

今天我们做一个企业级接口时，最容易被低估的东西，不是某个GET方法怎么查数据，也不是某个POST方法怎么落库，而是资源级别的 REST API 概览文档。很多项目一开始文档看起来很完整，每个方法都有请求参数、响应示例、错误码。可到了联调阶段，前端团队问分页参数到底统一叫limit还是$top，集成团队问ETag在更新时是不是强制传，安全团队问Authorization的格式是不是所有方法一致，运维团队问限流后从哪个 Header 里读取恢复时间。这个时候才发现，问题不在某一个接口写得不够细，而是缺了一份站在资源整体视角上的 API Overview。在 SAP 项目里，这个问题更常见。因为我们的接口经常横跨 ABAP On-Premise、SAP Gateway Foundation、S/4HANA 扩展、SAP BTP ABAP environment、RAP 暴露的 OData 服务，甚至还有 CAP 或 Integration Suite 中转出来的 REST 服务。单个方法文档解决的是局部问题，资源级概览文档解决的是一致性问题。它把一组围绕同一资源的 REST API 方法放在一张图景里看清楚，让读者知道这个资源能被查询、创建、修改、删除，也知道调用这些能力时需要哪些公共 Header、权限、状态码、错误格式和分页约定。资源级 REST API 概览的定位REST API Overview 不是某个方法的详细说明，也不是 OpenAPI 文件的重复截图。它更像接