---
name: API接口规格文档模版
id: ka-artifact_template-api-specification
asset_kind: artifact_template
lifecycle_status: active
authority: supporting
scope:
  - backend
  - frontend
products:
  - '*'
routes:
  - artifact_generation
primary_triggers:
  - API接口规格文档
  - 接口规格
  - API文档
  - 接口设计
  - API设计
  - 接口文档
  - 接口定义
priority: P1
specificity: 4
version: 1.0.0
last_reviewed: '2026-05-25'
owner_mechanism_id: mc-design-artifact-pack
consumes:
  - docs/architecture/00-架构决策记录.md
  - docs/architecture/01-架构设计文档.md
  - docs/architecture/02-数据库设计文档.md
emits:
  - docs/architecture/03-API接口规格文档.md
  - docs/api/openapi.yaml
required_evidence:
  - endpoint_field_tables
  - openapi_operation_coverage
type: acceptance_template
status: active
---

# API 接口规格文档

OpenAPI 权威路径: `docs/api/openapi.yaml`

## Endpoint: `METHOD /api/v1/resource`

### 基本信息

| endpoint_id | 用途 | 调用端 | 权限 | 幂等 | 限流 | 副作用 |
|-------------|------|--------|------|------|------|--------|

### 请求 Header 字段

| 字段路径 | 类型 | 必填 | 格式/约束 | 数据映射 | 说明 | 示例 |
|----------|------|------|-----------|----------|------|------|

### 请求 Path / Query 字段

| 字段路径 | 类型 | 必填 | 默认值 | 格式/约束 | 说明 | 示例 |
|----------|------|------|--------|-----------|------|------|

### 请求体字段

| 字段路径 | 类型 | 必填 | 可空 | 枚举/格式/校验 | 数据映射 | 说明 | 示例 |
|----------|------|------|------|----------------|----------|------|------|

### 响应体字段

| 字段路径 | 类型 | 必有 | 可空 | 枚举/格式 | 数据来源 | 说明 | 示例 |
|----------|------|------|------|-----------|----------|------|------|

### 错误与副作用

| 业务码 | HTTP 状态 | 触发条件 | 用户提示 | 可重试 | 状态/数据副作用 |
|--------|-----------|----------|----------|--------|-----------------|

### 验收场景

| 场景 | 输入 | 预期响应 | 数据/状态变化 | 验证证据 |
|------|------|----------|---------------|----------|

### 枚举值定义

| 枚举名 | 值 | 含义 |
|--------|------|------|

### 页面交互映射

| 页面操作 | 触发接口 | 加载状态 | 成功行为 | 失败行为 |
|---------|---------|---------|---------|---------|

### 接口规范检查

- [ ] 是否定义了接口版本号和演进策略（如 /api/v1/）
- [ ] 是否有幂等设计（写接口需标注幂等键或唯一约束）
- [ ] 错误码体系是否完整（业务码 + HTTP 状态码双映射）
- [ ] 是否有分页参数上限限制（防止恶意大翻页）
- [ ] 是否有接口限流策略（QPS/并发上限）
- [ ] 批量操作是否有数量上限（≤ 500 条）
