当前位置：首页 > news >正文

RESTFUL接口文档设计指南

news 来源：原创 2024/5/8 5:58:02

这里写目录标题

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路径设计如下：

https://api.demo.com/v1/hospitals
https://api.demo.com/v1/departments
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

请求方式

参数类型

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": "状态",
		},
		...
	]
  }