如何规范写RESTFUL API 接口文档

前言

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

1、文档概述

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

2、接口详情

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

1. 接口名称：简明描述功能（如“创建用户”）。

2. HTTP 方法：明确 GET/POST/PUT/DELETE 等。

3. URL 路径：如/api/v1/users/{id}，标注路径参数（{id}）。

4. 请求参数：

• Query 参数：类型、是否必填、示例（如 ?page=1&limit=10）。

• Path 参数：如 /users/{id}。

• Body 参数：JSON 结构示例，标注必填字段。

• Header 参数：如 Authorization: Bearer <token>。

5. 响应示例：

• 成功响应（HTTP 200）和失败响应（HTTP 4xx/5xx）的 JSON 结构。

• 包含不同场景的响应（如分页数据、空数据）。

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

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

1. 用户注册

2. path: /user/registers

3. method:post

4. 请求参数

5. 请求示例：

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

6. 相应示例

• 成功示例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"
        }
    ]
}