接口设计文档规范与网关治理.docx

RESTful接口设计文档规范与网关治理实例

（IT技术与产品文档·数据与实例为据）

第一章接口文档的定位与读者

接口文档的第一读者是写调用方的人，不是归档检查。判据：新人拿着文档不加询问能否在30分钟内写出第一个成功请求。华瑞优选商城开放平台改版前这条不过关，文档227页、示例却是2年前的版本，接入方平均首次调通耗时4.1小时。改版后按本文规范重写118个接口，首次调通中位数降到22分钟。

规范覆盖四件东西：风格约定（命名、版本、分页、幂等）、错误码表、报文示例、变更流程。每类文档字段固定，机器可读部分是硬要求——OpenAPI3.0定义文件是唯一事实源，网页文档从它生成，禁止手写正