API文档规范

API简介

在web项目前后台分离开发的过程中。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口；需要文档来说明、系统之间相互调用需要文档来记录接口协议等等。对于一个完整的项目，接口文档是至关重要的。

接口参数详细信息

接口文档最重要的是接口的详细信息，基本上应该满足以下几点

1. 接口名称
2. 功能说明
3. 提供方，调用方
4. 接口调用方式
5. 接口调用地址（必要时分别给出测试和生产的）
6. 一个调用的样例和返回的样例
7. 请求参数和返回参数：

API - 请求参数

• Headers 请求头

  接口的请求过程中可能由于编码导致乱码,如无特殊说明或响应头中的 Content-Type 未指定编码，请求和响应中的字节编码均使用 UTF-8

• 请求参数、返回数据

  请求参数和返回数据都分为：字段、说明、类型、备注、是否必填五个字段

接口备注

备注信息一般需要写上
请求参数示例、返回参数示例、数据请求异常（失败）示例

1. 请求参数 / 返回参数 示例

{
    "code": 0,
    "data": {
        "data1": "请求数据参数1",
        "data2": "请求数据参数2",
    },
    "msg": "OK!"
}

3. 数据请求异常示例

{
    "data": [],
    "subMsg": "用户名不能为空，请检查",
    "subCode": "XXX.XXX-XXX",
    "msg": "类型错误",
    "code": 300,
    "sign": ""
}

接口辅助工具

部门编写接口文档的工具 eolinker ，可以模拟数据辅助测试。