creekmoon 标准化 API 文档编写规范
本规范定义统一的接口文档格式，用于产出可维护、便于对接方理解的 API 文档。
目标读者：对接方开发人员 输出格式：Markdown（可导出 HTML） 适用场景：开放接口、REST API、资源接口、对外服务文档
文档整体结构（必须按此顺序）
# [平台/系统名称] 资源接口说明
## 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 |
请求示例：
{
"xxx": "示例",
"pageNum": 1,
"pageSize": 20
}
6.3 响应参数
| 字段 | 类型 | 必然存在 | 说明 | 示例值 |
|---|---|---|---|---|
| xxx | String | ✅ | 说明 | "示例" |
响应示例：
{
"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 结构
- 枚举值在附录中有对照说明