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	狀态

備注

• 根據篩選條件查詢使用者資訊，若沒有參數則傳回全部使用者資訊