---
name: api-specification
id: ka-artifact_template-api-specification
asset_kind: acceptance_template
lifecycle_status: active
authority: supporting
scope:
  - backend
  - frontend
products:
  - '*'
routes:
  - artifact_generation
primary_triggers:
  - API接口规格文档
  - 接口规格
  - API文档
  - 接口设计
  - API设计
  - 接口文档
  - 接口定义
priority: P1
specificity: 4
version: 1.1.0
last_reviewed: '2026-06-01'
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
artifact_schema:
  kind: api_spec
  required_sections:
    - 基本信息
    - 请求 Header 字段
    - 请求 Path
    - 请求体字段
    - 响应体字段
    - 错误与副作用
    - 验收场景
    - 枚举值定义
    - 页面交互映射
  required_tables:
    - 基本信息表
    - 请求Header字段表
    - 请求Path/Query字段表
    - 请求体字段表
    - 响应体字段表
    - 错误与副作用表
    - 验收场景表
    - 枚举值定义表
    - 页面交互映射表
  required_fields:
    基本信息表:
      - endpoint_id
      - 用途
      - 调用端
      - 权限
      - 幂等
    请求体字段表:
      - 字段路径
      - 类型
      - 必填
      - 枚举
      - 数据映射
      - 说明
    响应体字段表:
      - 字段路径
      - 类型
      - 必有
      - 可空
      - 数据来源
      - 说明
  required_artifacts:
    - OpenAPI 文件
  forbidden_gaps:
    - endpoint缺请求或响应字段表
stages: ["架构设计", "详细设计"]
---

# API 接口规格文档

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

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

### 基本信息

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

### 请求 Header 字段

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

### 请求 Path / Query 字段

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

### 请求体字段

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

### 响应体字段

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

### 错误与副作用

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

### 验收场景

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

### 枚举值定义

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

### 页面交互映射

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

### 接口规范检查

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