5986922003
包含完整的产品管理文档模板： - PRD 需求文档模板 - 功能点拆解模板 - API 文档模板 - 测试用例模板 - 发布与回滚模板 - ADR 决策记录模板 - 会议纪要模板
92 lines
1.9 KiB
Markdown
92 lines
1.9 KiB
Markdown
---
|
||
type: template
|
||
template_id: API-Doc
|
||
tags:
|
||
- 文档/API
|
||
status: design
|
||
created: {{date}}
|
||
updated: {{date}}
|
||
phase: 2025
|
||
attribute: 工程态
|
||
---
|
||
|
||
# 00.3｜API 文档母版
|
||
|
||
> [!summary] 接口基础信息
|
||
> * **时间阶段**：`2025` / `2026` (必填)
|
||
> * **文档属性**：`工程态` / `注册态` (必填)
|
||
> * **接口编号**：`API-XXXX`
|
||
> * **接口名称**：
|
||
> * **所属服务**：`前端` / `后端` / `算法服务`
|
||
> * **接口版本**：`Vx.x`
|
||
> * **维护人**：
|
||
|
||
---
|
||
|
||
## 1. 请求说明 (Request)
|
||
|
||
* **URL**: `/api/v1/resource/...`
|
||
* **Method**: `GET` / `POST` / `PUT` / `DELETE`
|
||
* **Content-Type**: `application/json`
|
||
|
||
### 1.1 Header 说明
|
||
| Key | Value | 必填 | 说明 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| Authorization | Bearer token | 是 | 用户凭证 |
|
||
|
||
### 1.2 请求参数 (Body / Query)
|
||
|
||
| 参数名 | 类型 | 必填 | 示例值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| `id` | String | 是 | "12345" | 资源 ID |
|
||
| `name` | String | 否 | "Test" | 名称 |
|
||
|
||
---
|
||
|
||
## 2. 返回说明 (Response)
|
||
|
||
### 2.1 成功响应示例 (HTTP 200)
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": "12345",
|
||
"status": "active"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 字段说明
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `code` | Number | 业务状态码 |
|
||
| `data` | Object | 业务数据 |
|
||
|
||
---
|
||
|
||
## 3. 错误码定义 (Error Codes)
|
||
|
||
| 错误码 (code) | 含义 | HTTP Status | 处理建议 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| 40001 | 参数错误 | 400 | 检查参数格式 |
|
||
| 40100 | 未授权 | 401 | 跳转登录 |
|
||
| 50000 | 系统内部错误 | 500 | 联系管理员 |
|
||
|
||
---
|
||
|
||
## 4. 权限与安全
|
||
|
||
* **鉴权方式**：`Token` / `Cookie` / `API Key`
|
||
* **权限控制**：仅 `Admin` 角色可调用
|
||
|
||
---
|
||
|
||
## 5. 版本变更记录
|
||
|
||
| 版本 | 日期 | 变更人 | 变更内容 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| V1.0 | {{date}} | | 初始版本创建 |
|