如何写好接口文档?

1. HTTP携带信息的方式 url headers body: 包括请求体,响应体 2. 分离通用信息 一般来说,headers里的信息都是通用的,可以提前说明,作为默认参数 3. 路径中的参数表达式 URL中参数表达式使用{}的形式,参数包裹在大括号之中{paramName} 例如: /api/user/{userId} /api/user/{userType}?age={age}&gender={gender} 4. 数据模型定义 数据模型定义包括: 路径与查询字符串参数模型 请求体参数模型 响应体参数模型 数据模型的最小数据集: 名称 是否必须 说明 “最小数据集”(MDS)是指通过收集最少的数据,较好地掌握一个研究对象所具有的特点或一件事情、一份工作所处的状态,其核心是针对被观察的对象建立起一套精简实用的数据指标。最小数据集的概念起源于美国的医疗领域。最小数据集的产生源于信息交换的需要,就好比上下级质量技术监督部门之间、企业与质量技术监督部门之间、质量技术监督部门与社会公众之间都存在着信息交换的需求。 一些文档里可能会加入字段的类型,但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化,大部分数据类型都是字符串。一些特殊的类型,例如枚举类型的字符串,可以在说明里描述。 另外:数据模型非常建议使用表格来表现。 举个栗子🌰: 名称 是否必须 说明 userType 是 用户类型。commom表示普通用户,vip表示vip用户 age 否 用户年龄 gender 否 用户性别。1表示男,0表示女 5. 请求示例 // general POST http://www.testapi.com/api/user // request payload { "name": "qianxun", "age": 14, "like": ["music", "reading"], "userType": "vip" } // response { "id": "asdkfjalsdkf" } 6. 异常处理 异常处理最小数据集...

2018-01-29 22:01:55 · 1 min · Eddie Wang