【IT修真院】接口文档规范以及示例

概述

所有项目接口文档，麻烦上心整理，文档不是给自己看的，只有自己才看得懂的文档就不要放上去浪费其他同学的时间了。

所有文档至少包含以下信息：

1.接口功能
2.接口路径
3.接口入参
4.接口出参
5.各字段说明、约定值、是否必填、默认参数
6.复杂数据结构给出出范例

内容比较多，长期保持迭代的项目可将文档按照功能模块拆分

示例：

1. 命名

   1. 所有接口均需符合restful命名风格，相关api设计规则可参考阮一峰-RESTful API 设计指南文章
       

2. 校验

   1. 所有接口需日志记录关键入参，并对相关入参做好相关检验，参数缺失、异常必须给出异常码以及对应异常信息，方便查错。
   2. 发送短信、语音，身份验证等收费接口，做好安全校验（加密或加图形验证码等），避免机器恶意的接口调用造成经济损失
   3. 所有需要关于当前用户数据的相关操作，登录用户信息由后端直接从session、cookie、token中获取，禁止由前端进行传递。

3. 设计

   1. 从性能考虑，原则上后端接口中不对数据进行复杂处理，仅将相关业务数据返回即可，故非特殊情况，不写复杂数据处理逻辑。