15.如何规范写RESTFUL API 接口文档

书诚小驿2025/03/03前端知识库NodeJS Restful

前言

编写规范的 RESTful API 接口文档是确保API文档清晰、一致，方便其他开发者使用促进团队协作高效、降低沟通成本的关键。

1、文档概述

基于RESTFUL API接口规范
基于JWT身份认证
使用CORS跨域
接口基础请求地址：http://127.0.0.1:3000/api/v1
使用JSON格式进行数据通信

2、接口详情

资源路径：按功能模块分组（如用户管理、订单管理）。每个接口需包含以下内容

接口名称：简明描述功能（如“创建用户”）。
HTTP 方法：明确 GET/POST/PUT/DELETE 等。
URL 路径：如 /api/v1/users/{id}，标注路径参数（{id}）。
请求参数：

Query 参数：类型、是否必填、示例（如 ?page=1&limit=10）。
Path 参数：如 /users/{id}。
Body 参数：JSON 结构示例，标注必填字段。
Header 参数：如 Authorization: Bearer <token>。

响应示例：

成功响应（HTTP 200）和失败响应（HTTP 4xx/5xx）的 JSON 结构。
包含不同场景的响应（如分页数据、空数据）。

错误码表：如 4001: 参数缺失、4010: 无权限。

3、用户注册接口文档（`demo`）

用户注册
path: /user/registers
method:post
请求参数

字段名	字段类型	是否必须
username	string	是
email	string	是
phone	string	是
password	string	是
avatar	string	否

请求示例：

{
  "username": "xiaoyi",
  "email": "151****7344@163.com",
  "phone": "151****7344",
  "password": "123456"
}

相应示例

成功示例success

{
  "username": "xiaoyi",
  "email": "151****7344@163.com",
  "password": "123456",
  "phone": "151****7344",
  "avatar": null,
  "createAt": "2025-03-03T09:49:12.954Z",
  "updateAt": "2025-03-03T09:49:12.954Z",
  "_id": "67c57b2606ded7d7bdb74df2",
  "__v": 0
}

错误示例error

{
  "errors": [
    {
      "type": "field",
      "value": "x",
      "msg": "用户名长度不能小于2",
      "path": "username",
      "location": "body"
    }
  ]
}

目录