79 lines
1.6 KiB
Markdown
79 lines
1.6 KiB
Markdown
|
# API 文档模板
|
|||
|
|
|
|||
|
|
## 元数据
|
|||
|
|
- 需求编号：
|
|||
|
|
- 创建时间：YYYY-MM-DD
|
|||
|
|
- 创建人：
|
|||
|
|
- 版本：1.0.0
|
|||
|
|
|
|||
|
|
## API 概述
|
|||
|
|
[API 概述]
|
|||
|
|
|
|||
|
|
## 基础信息
|
|||
|
|
- API 名称：
|
|||
|
|
- API 版本：
|
|||
|
|
- 描述：
|
|||
|
|
- 认证方式：
|
|||
|
|
|
|||
|
|
## 端点列表
|
|||
|
|
|
|||
|
|
### 接口 1：[接口名称]
|
|||
|
|
- **请求方式**：GET/POST/PUT/DELETE
|
|||
|
|
- **请求路径**：/api/xxx
|
|||
|
|
- **功能描述**：
|
|||
|
|
- **请求参数**：
|
|||
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
|||
|
|
| ------ | ---- | ---- | ---- | ------ |
|
|||
|
|
| param1 | String | 是 | 参数1描述 | value1 |
|
|||
|
|
| param2 | Integer | 否 | 参数2描述 | 100 |
|
|||
|
|
- **请求体**：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"field1": "value1",
|
|||
|
|
"field2": 123
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **响应参数**：
|
|||
|
|
| 参数名 | 类型 | 描述 |
|
|||
|
|
| ------ | ---- | ---- |
|
|||
|
|
| code | Integer | 响应码 |
|
|||
|
|
| message | String | 响应信息 |
|
|||
|
|
| data | Object | 响应数据 |
|
|||
|
|
- **成功响应示例**：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"result": "ok"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **错误响应示例**：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 400,
|
|||
|
|
"message": "Bad Request",
|
|||
|
|
"data": null
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- **状态码**：
|
|||
|
|
| 状态码 | 描述 |
|
|||
|
|
| ------ | ---- |
|
|||
|
|
| 200 | 成功 |
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未认证 |
|
|||
|
|
| 403 | 无权限 |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
- **注意事项**：
|
|||
|
|
- 注意事项1
|
|||
|
|
- 注意事项2
|
|||
|
|
|
|||
|
|
## 变更历史
|
|||
|
|
| 版本 | 时间 | 变更内容 | 变更人 |
|
|||
|
|
| ---- | ---- | -------- | ------ |
|
|||
|
|
| 1.0.0 | YYYY-MM-DD | 初始版本 | |
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
- [需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)
|
|||
|
|
- [设计文档](../design/YYYY-MM-DD-00X-设计名.md)
|