# Creekmoon Apidoc Spec

> 标准化 API 文档编写规范。产出统一格式的接口文档——包括概述、版本历史、环境配置、通用数据结构、分页说明，以及每个接口的「接口说明 / 请求参数 / 请求示例 / 响应参数 / 响应示例」。用户在编写接口文档、API 文档、对外开放接口说明、资源接口规范时自动使用。

- Skill: `creekmoon/creekmoon-apidoc-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add creekmoon/creekmoon-apidoc-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/creekmoon/creekmoon-apidoc-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: creekmoon (https://skillmd.com/u/creekmoon)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/creekmoon/creekmoon-apidoc-spec

---


# 标准化 API 文档编写规范

本规范定义统一的接口文档格式，用于产出可维护、便于对接方理解的 API 文档。

**目标读者**：对接方开发人员
**输出格式**：Markdown（可导出 HTML）
**适用场景**：开放接口、REST API、资源接口、对外服务文档

---

## 文档整体结构（必须按此顺序）

```markdown
# [平台/系统名称] 资源接口说明

## 1. 概述

[1-2 段说明文档用途、调用前准备。若需先获取 AccessToken / ClientToken，在此说明。]

## 2. 版本历史

| 版本 | 日期 | 修改内容 | 作者 |
|------|------|----------|------|
| 1.0 | yyyy-MM-dd | 初始版本 | 姓名 |
| 1.1 | yyyy-MM-dd | 变更说明 | 姓名 |

## 3. 环境配置

### 3.1 测试环境地址

| 接口名称 | 测试环境 URL |
|----------|--------------|
| [接口1] | https://... |
| [接口2] | https://... |

## 4. 数据获取流程

### 4.1 标准数据获取流程

[用 Mermaid 或文字描述调用顺序，如：先获取主数据 → 用主键调用关联数据接口]

### 4.2 流程说明

[简要说明依赖关系、必选步骤]

## 5. 通用数据结构

### 5.1 统一响应格式

所有接口遵循统一响应结构，用 `code==200` 判断是否成功：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "list": [...],
    "total": 100,
    "pages": 10,
    "pageNum": 1,
    "pageSize": 10
  }
}
```

### 5.2 分页参数说明

| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|------|------|----------|--------|------|
| pageNum | Integer | - | 1 | 页码，从 1 开始，最小值为 1 |
| pageSize | Integer | - | 10 | 每页记录数，最大值为 500 |

## 6. [业务模块1] 接口

### 6.1 接口说明

- **接口地址**：`https://...`
- **接口功能**：[一句话描述]
- **请求方式**：POST / GET
- **Content-Type**：application/json

### 6.2 请求参数

| 字段 | 类型 | 是否必填 | 说明 | 示例值 |
|------|------|----------|------|--------|
| xxx | String | ✅ | 说明 | "示例" |
| pageNum | Integer | - | 页码 | 1 |
| pageSize | Integer | - | 每页条数 | 20 |

**请求示例**：

```json
{
  "xxx": "示例",
  "pageNum": 1,
  "pageSize": 20
}
```

### 6.3 响应参数

| 字段 | 类型 | 必然存在 | 说明 | 示例值 |
|------|------|----------|------|--------|
| xxx | String | ✅ | 说明 | "示例" |

**响应示例**：

```json
{
  "code": 200,
  "msg": "ok",
  "data": {
    "total": 3,
    "list": [
      {
        "xxx": "示例"
      }
    ],
    "pageNum": 1,
    "pageSize": 10,
    "pages": 1
  }
}
```

## 7. [业务模块2] 接口
...

## 10. 附录

### 10.1 通用枚举值对照

[按需列出：字典字段对应取值、状态码、类型码、业务枚举等]
```

---

## 每个接口必须包含的章节

对**每一个**接口，必须包含以下三块（顺序固定）：

1. **接口说明**：URL、功能、请求方式、Content-Type
2. **请求参数**：表格（字段、类型、是否必填、说明、示例值）+ 请求示例 JSON
3. **响应参数**：表格（字段、类型、必然存在、说明、示例值）+ 响应示例 JSON

每个接口的请求参数和响应参数必须**自解释**，读者不跳转到任何其他章节也能完整理解本接口。

---

## 章节复用规则

### 默认策略：全量展开

**默认情况下，每个接口的请求参数和响应参数必须完整列出字段表与示例 JSON，禁止用文字描述代替。**

### 例外：允许带链接的复用引用

仅当同时满足以下全部条件时，才允许简写：

1. 当前接口与被引用接口的参数结构**完全一致**，无任何字段差异；
2. 该结构字段较多，全量展开会大幅拉长篇幅；
3. 引用必须使用**可点击的 Markdown 链接**，不得使用纯文字（如"同上"、"见前文"、"参考 7.1.2"）。

即使使用引用，也必须在同一章节额外说明**本接口与引用结构的差异点**；若无任何差异，应注明"完全一致，无额外字段"。

### 复用的目标：优先共享结构，而非接口章节

当多个接口共享同一复杂嵌套对象时，应将该结构提炼到**`## 5. 通用数据结构`** 或**`## 附录`**中，以命名的 `###` 标题定义（如 `### 报价项结构`），接口章节中使用链接指向该命名结构。

**禁止**直接链接到另一个接口的 `响应参数` 章节（如 `见 #### 7.1.2 响应参数`），这会造成接口间耦合，增加读者的跳转负担。

### 禁止写法（反例）

```text
#### 7.3.2 响应参数

结构同【7.1.2 响应参数】。当 isCompleted=true 时询价全部完成，results 为最终报价列表。
```

上述写法同时违反两条规则：①纯文字引用，没有可跳转的链接；②链接目标是接口章节而非共享结构。

---

## 参数表规范

- **请求参数表**列：`字段 | 类型 | 是否必填 | 说明 | 示例值`
- **响应参数表**列：`字段 | 类型 | 必然存在 | 说明 | 示例值`
- 类型统一用：`String`、`Integer`、`Long`、`Boolean`、`Object`、`Array`
- 是否必填/必然存在：统一使用 `✅` 或 `-`
- `✅` 表示必填或必然存在，`-` 表示选填

### 字段说明规则

- **普通字段**：保持现状，在说明中写清字段业务含义即可，无需额外约定
- **字典字段**：说明中必须明确写出「字典字段」，并在说明或附录中列出对接方可见的「字典值 → 含义」对照；**不要暴露内部字典类型编码（即系统内部按哪个 code 大类存储的标识），该信息对对接方无意义**
- **非字典但常见值字段**：说明中直接写明其为**非字典字段**，并补充常见值示例；示例值列应体现这些常见值，不要求进入附录

### 字段说明写法示例

- **普通字段**：`客户名称`
- **字典字段**：`字典字段，取值见 [附录「订单状态」](#附录小节标题锚点)`
- **非字典但常见值字段**：`非字典字段，常见值如 wechat、alipay、bank`

锚点写法说明：Markdown 标题会自动生成锚点，中文标题直接使用标题文字（去掉标点、空格替换为 `-`）。例如附录小节为 `### 订单状态`，则链接写为 `[附录「订单状态」](#订单状态)`。

> 反例（不要这样写）：`字典 lastMileServiceLevel：OD-室外配送、IDD-室内配送`——这里 `lastMileServiceLevel` 是系统内部字典大类编码，对接方不需要知道，只需说明字段含义与各取值即可。

---

## 示例与 JSON 格式

- 请求示例、响应示例一律用代码块包裹，语言标注为 `json`
- JSON 保持格式美观，字段与示例值应对齐表格
- 若为分页接口，响应示例中 `data` 需包含 `list`、`total`、`pages`、`pageNum`、`pageSize`

---

## 枚举与附录

- 若字段属于**字典字段**，说明中必须明确标注「字典字段」，并在**附录**中集中列出该字段对应的「字典值 → 含义」对照表；附录只需呈现对接方可见的字典值与含义，**不需要出现内部字典类型编码**
- 附录中每个枚举/字典对照小节须使用独立的 `###` 标题（如 `### 订单状态`），该标题即为 Markdown 锚点目标；字段说明列中的引用须使用 Markdown 链接指向该标题，实现文档内跳转
- 若接口返回固定枚举值（如状态码、类型码），也应在**附录**中集中列出「枚举值 → 含义」对照表
- 若字段**不是字典字段**，但业务上存在若干常见值，则只在字段说明和示例值中体现，不进入附录
- 附录可按模块拆分：通用枚举、业务枚举

---

## 与 TRD 的区分

| 维度 | TRD | 本规范（对外接口文档） |
|------|-----|------------------------|
| 读者 | 内部架构/开发 | 对接方开发 |
| 内容 | 模块划分、接口契约、NFR | 具体 URL、请求/响应字段、示例 |
| 用途 | 技术方案评审 | 联调、对接、集成 |

本规范产出的是**对接用文档**，需要具体到 URL、字段、示例，方便对方直接调用。

---

## 自检清单

- [ ] 文档有「概述」「版本历史」「环境配置」
- [ ] 每个接口包含「接口说明」「请求参数」「响应参数」
- [ ] 每个接口的参数章节自解释，无需跳转到其他接口章节也能完整理解
- [ ] 若存在引用复用，均使用可点击 Markdown 链接，且引用目标为通用结构或附录命名结构，而非其他接口的参数章节
- [ ] 参数表列完整，示例值与说明一致
- [ ] 字典字段已在说明中明确标注「字典字段」，附录中能找到对接方可见的「字典值 → 含义」对照，且未暴露内部字典类型编码
- [ ] 非字典但常见值字段已在说明中直接提示常见值，且示例值有体现
- [ ] 响应结构符合统一格式（code/msg/data）
- [ ] 分页接口明确 pageNum/pageSize 及 data 结构
- [ ] 枚举值在附录中有对照说明