RESTFUL接口文档设计指南

这里写目录标题

• API简要描述
• 协议
• 域名
• 版本化你的API
• 路径
• 请求类型
• • 常用类型
  • • GET
    • • 单条数据查询
      • 请求列表
    • POST
    • • 单条数据插入
      • 批量数据插入
    • PUT
    • DELETE
    • • 单条数据删除
      • 批量删除
  • 不常用
  • • PATCH
• 状态码
• 错误处理
• 请求参数规范
• 返回结构与参数说明
• RESTFUL接口文档示例
• • • • • 简要描述
        • 请求URL
        • 请求方式
        • 参数类型
        • 参数
        • 返回示例
        • 返回参数说明
        • 备注

API简要描述

注明作者信息，API功能

协议

通信协议使用https

域名

API应该部署在专用域名

例如：https://api.demo.com

版本化你的API

版本号放在API的url中

例如：https://api.demo.com/v1

路径

表示API的具体网址,restful风格中通常网址标识资源，只能有名词，且与数据库表名一致，常用复数形式。当使用API提供医院的信息，还包括部门，医生的信息时，API路径设计如下：

1. https://api.demo.com/v1/hospitals
2. https://api.demo.com/v1/departments
3. https://api.demo.com/v1/doctors

请求类型

使用http动词表示请求类型

对同一资源所做的 增/删/改/查 操作的API，路径通常一样，只有发起请求的类型不同

前端写请求拦截器时通常把参数名为params的处理为query类型，把参数名为data的处理为body类型

如下：

常用类型

GET

常用于向服务器请求获取数据，可获取单条或列表

单条数据查询

请求参数通常拼接在URL后，即参数类型为query，如下：

https://api.demo.com/v1/doctors?id=2

请求列表

- API中通常需要加上list
- 常使用分页查询模式（传参pageIndex，pageSize）
- 可加入额外参数进行条件查询
- 参数类型为query
           

分页查询医生列表的API 可设计如下：

https://api.demo.com/v1/doctors/list?pageIndex=1&pageSize=10

POST

常用于向服务器请求新建资源，即对数据库进行插入操作的API

单条数据插入

请求参数通常放在请求体body里，参数类型为body，新增一个医生数据的API路径如下：

https://api.demo.com/v1/doctors

批量数据插入

• 路径通常需要加入batch
• 参数通常为数组

• 参数类型通常为body

  批量增加医生数据的API路径如下：

https://api.demo.com/v1/doctors/batch

PUT

常用于向服务器请求修改资源，即对数据库进行修改操作的API

请求参数通常放在body里，例如修改一个医生信息的API路径如下：

https://api.demo.com/v1/doctors

DELETE

常用于向服务器请求删除资源，即对数据库进行删除数据操作的API

单条数据删除

参数通常拼接在url里，参数类型为query，删除一个医生信息的API路径如下：

https://api.demo.com/v1/doctors

批量删除

• 参数通常放在body里
• 参数通常为数组

• 路径通常要加batch

  批量删除医生的API路径如下：

https://api.demo.com/v1/doctors/batch

不常用

PATCH

状态码

常用状态码如下：

• 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
• 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
• 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
• 204 NO CONTENT - [DELETE]：用户删除数据成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
• 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
• 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
• 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
• 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
• 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。

• 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

  用于修改部分信息，参数为只需要修改的字段内容，而put需要提供该数据所有字段信息

错误处理

后台进行错误拦截后输入错误提示信息用于前台展示给用户

请求参数规范

将请求参数按参数名，类型，参数说明的表格形式展示，如下：

参数名称	类型	参数说明	是否必须
pageIndex	number	页码,默认为1	false
pageSize	number	页大小,默认为10	false

返回结构与参数说明

返回结构通常固定为以下内容：

{
	code: 200,
	message: 'success',
	data: {} / []
}
           

参数名	类型	说明
id	bigint	id
name	string	名称
isRequired	int	是否必填，1代表是，0代表否，默认1
type	string	类型

RESTFUL接口文档示例

简要描述

• 作者：XXX
• 分页查询用户信息接口

请求URL

• /demo/user/list

请求方式

• GET

参数类型

• QUERY

参数

参数名称	类型	参数说明	是否必须
pageIndex	number	页码,默认为1	false
pageSize	number	页大小,默认为10	false

返回示例

{
    "code": 200,
    "message": "success",
    "data": [
		{
			"id": "用户id",
			"name": "用户名",
			"nickName": "昵称",
			"role": "角色",
			"status": "状态",
		},
		{
			"id": "用户id",
			"name": "用户名",
			"nickName": "昵称",
			"role": "角色",
			"status": "状态",
		},
		...
	]
  }
           

返回参数说明

参数名	类型	说明
id	int	用户id
name	varchar	用户名
nickName	varchar	昵称
role	varchar	角色
status	varchar	状态

备注

• 根据筛选条件查询用户信息，若没有参数则返回全部用户信息