文章目录
- 一、接口文档
- 1.1 接口文档介绍
- 1.2 接口文档内容
- 二、接口文档解析
- 2.1 登录接口文档
- 2.1.1 基本信息
- 2.1.2 请求参数
- 2.1.3 返回数据
- 2.2 登录接口文档解析
一、接口文档
1.1 接口文档介绍
接口文档：又称为API文档，一般是由后端开发人员所编写的，用来描述系统所提供接口信息的文档。
1、为什么要写接口文档 - 能够让前端开发与后端开发人员更好的配合，提高工作效率。(有一个统一参考的文件) - 项目迭代或者项目人员更迭时，方便后期人员查看和维护。 - 方便测试人员进行接口测试。 2、展现形式 - word 文档形式 - Excel 表格式形式 - pdf 文档形式。1.2 接口文档内容
一个规范的接口文档，要包含以下信息：
1、基本信息
- 资源路径（协议和域名在 “系统信息”中）
- 请求方法
- 接口描述
2、请求参数
- 请求头（Content-Type。描述请求体的数据类型！）
- 请求体（包含具体的请求参数名称、参数类型、是否必须、示例、备注）
3、返回数据
- 不同情况的响应状态码（成功）
- 响应数据（包含具体的响应数据名称、类型、是否必须、默认值、示例、备注)
二、接口文档解析
2.1 登录接口文档
2.1.1 基本信息
- Path： http://ihrm2-test.itheima.net/api/sys/login
- Method： POST
- 接口描述:
2.1.2 请求参数
Headers
| 参数名称 | 参数值 | 是否必须 | 示例 | 备注 |
|---|---|---|---|---|
| Content-Type | application/json | 是 |
Body
| 名称 | 类 | 是否必须 | 默认值 | 备注 | 其他信息 |
|---|---|---|---|---|---|
| mobile | string | 必须 | 手机号 | ||
| password | string | 必须 | 密码 |
2.1.3 返回数据
- 操作成功响应状态码：200
- 错误码描述：
- 10000：操作成功！
- 20001：用户名或密码错误
- 99999：抱歉，系统繁忙，请稍后重试！
| 名称 | 类型 | 是否必须 | 默认值 | 备注 |
|---|---|---|---|---|
| success | bool | 是 | 操作成功标记 | |
| code | int | 是 | 10000 | 错误码 |
| message | string | 是 | 操作成功！ | 消息 |
| data | string | 是 | 令牌（token） |
{"success":true,"code":10000,"message":"操作成功！","data":"xxx"}{"success":false,"code":20001,"message":"用户名或密码错误","data":null}{"success":false,"code":99999,"message":"抱歉，系统繁忙，请稍后重试！","data":null}2.2 登录接口文档解析
接口文档的解析本质：从接口文档中，找出 http 请求所需要的 数据信息。
1、http请求相关数据： ——①请求方法 ——②URL ——③请求头 ——④请求体（数据类型） 2、http响应相关数据：预期结果 ——①响应状态码 ——②响应体- 以 “登录” 为例：
- 请求方法：POST
- URL：http://ihrm2-test.itheima.net/api/sys/login
- 请求头：
Content-Type:application/json - 请求体：{“mobile”:”13800000002”, “password”:”888itcast.CN764%…”}
- 响应状态码：200
- 错误码：
- 10000：操作成功！
- 20001：用户名或密码错误
- 99999：抱歉，系统繁忙，请稍后重试！
- 错误码：
