在 API 文档中写什么

在编写 API 文档时，需要包含以下内容：

1. API 端点: 包含所有 API 的终端点列表，每个端点应该包含请求类型，URL 和一个简短的描述，如下所示：

## Endpoints

### Get User
* URL: /users/{id}
* Method: GET
* Description: Retrieves user information by ID.

2. 请求参数: URL 查询参数，请求头参数和请求体参数应该都在文档中进行描述，如下所示：

## Request Parameters

### Query Parameters

| Parameter | Type    | Required | Description                     |
|-----------|---------|----------|---------------------------------|
| name      | string  | no       | Filter by name                   |
| age       | number  | no       | Filter by age                   |

### Request Headers

| Header | Type    | Required | Description                     |
|--------|---------|----------|---------------------------------|
| Authorization  | string  | yes      | Access token for authorization  |

### Request Body

| Parameter | Type    | Required | Description                     |
|-----------|---------|----------|---------------------------------|
| name      | string  | yes      | User's name                      |
| age       | number  | yes      | User's age                      |

3. 响应信息: 根据请求类型和响应状态码，对每个端点的响应进行描述，包括响应头和响应正文，如下所示：

## Response Information

### Success Response

* Status Code: 200 OK
* Body:

```json
{
  "name": "John",
  "age": 18,
  "gender": "male"
}

Error Response

• Status Code: 404 Not Found
• Body:

{
  "error": "User not found"
}

4. **示例请求和响应**: 包含请求和响应的示例，以便开发人员快速了解如何使用 API，如下所示：

```markdown
## Sample Request

```http
GET /users/123 HTTP/1.1
Host: example.com
Authorization: Bearer <access_token>

Sample Response

{
  "name": "John",
  "age": 18,
  "gender": "male"
}

Error Response

{
  "error": "User not found"
}

在编写 API 文档时，应该尽可能详细地描述每个端点并提供示例请求和响应，以使开发人员轻松使用 API。