一、核心结论：API 文档设计的本质与最短路径
API 文档设计的本质是：使用基于的领域特定语言（DSL），以人类可读且机器可解析的方式，定义API的端点、请求/响应结构、参数及数据模型。
最短操作路径：编写一个.apib文件 → 按照规范格式定义元数据、资源组、资源、操作、请求/响应示例、数据模型 → 使用工具（如Aglio、）验证并生成可视化文档或Mock服务器。
标准文档模板（直接可用）：
: 1A
HOST:
# 我的API
这是一个示例API文档。
## 用户 [/users]
### 获取所有用户 [GET]
+ 200 (/json)
+
+ users (array)
+ ()
+ id: 1 ()
+ name: 张三 ()
二、API 文档的标准结构（100%符合官方规范）
API 1A版本规定，文档必须按以下顺序组织（缺失任意部分将导致解析失败）：
| 区块 | 必选 | 说明 | 示例 |
|---|---|---|---|
| 标识 | 是 | 第一行必须是: 1A |
: 1A |
| HOST | 否 | 全局API基础URL | HOST: |
| 元数据 | 否 | 键值对，如版本、许可证 | META: =2.0 |
| API名称与描述 | 是 | #标题后跟描述 |
# 用户管理API |
| 资源组 | 否 | ## 组名，用于逻辑分组 |
## 用户相关接口 |
| 资源 | 是 | ### 资源路径，描述单个资源 |
### /users |
| 操作 | 是 | #### [HTTP方法]，定义端点行为 |
#### 获取用户列表 [GET] |
| 参数 | 视操作而定 | URI参数、查询参数、头部 | + |
| 请求/响应 | 至少一个响应 | 使用+ 和+ |
+ 200 (/json) |
| 数据模型 | 推荐 | 使用MSON定义可复用结构 | ## 数据模型 |
三、分步设计操作指南（可直接复制执行）
步骤1：创建文件并声明格式
新建文件api-.apib，首行必须为：
: 1A
步骤2：定义全局信息（HOST与元数据）
HOST:
META: =API团队
META: =2026-03-31
步骤3：编写资源与操作（核心）
每个操作必须包含：HTTP方法、URI、至少一个响应。
示例：带查询参数的GET操作
### 查询订单 [/{?,limit}]
#### 获取订单列表 [GET]
+
+ (enum[], 可选) - 订单状态
+ 示例：POST创建操作（带请求体）
### 创建订单 [/]
#### 创建新订单 [POST]
+ (/json)
+
+ : 5 (, 必填)
+ : 2 (, 必填)
+ 201 (/json)
+
+ : 1002 ()
步骤4：使用MSON定义可复用数据模型（避免重复）
在文档末尾（或资源组之后）定义：
## 数据模型
### 订单对象 ()
+ id: 1001 (, 必填) - 订单ID
+ : (enum[])
+ paid
+ 在响应中引用：
+ 200 (/json)
+ (订单对象)
步骤5：验证并生成文档
使用官方验证工具：
# 安装（官方C++解析器）
npm -g
# 验证语法
-l api-.apib
# 生成HTML
-o api-doc.html api-.apib
四、高频疑难与解决方案（覆盖全流程需求）
问题1：如何处理需要认证（API Key / Token）的接口？
官方方案：在操作或全局添加参数
### 获取用户信息 [GET]
+
+
: {token}
+ 200 (/json)
+
+ : alice ()
或者通过# API名称下定义全局+ 。
问题2：如何定义嵌套数组或复杂JSON？
使用MSON缩进表示嵌套：
+
+ ()
+ : 2026-03-31T10:00:00Z ()
+ tags (array[])
+ (array[])
+ ()
+ score: 0.95 ()
问题3：如何生成Mock服务器用于前端联调？
使用api-mock工具：
npm -g api-mock
api-mock api-.apib --port 3000
所有定义的请求路径会返回示例响应中的第一个响应体。
问题4：如何定义URI参数（如/users/{id}）？
在资源URI中使用{变量名}，并在操作下定义：
### 用户详情 [/users/{id}]
#### 获取单个用户 [GET]
+
+ id: 1 (, 必填) - 用户ID
+ 200
+
+ id: 1
+ name: 李四
问题5：文档中如何包含二进制文件上传（/form-data）？
使用+ 指定-Type，并添加body说明：
+ (/form-data; =---)
+ Body
----
-: form-data; name="file"; ="photo.jpg"
-Type: image/jpeg
[二进制数据]
------
五、权威参考与工具链
| 工具/资源 | 用途 | 官方地址 |
|---|---|---|
| API 规范 | 完整语法定义 | |
| 解析器与验证器（C++） | ||
| Aglio | 生成HTML/PDF文档 | |
| 命令行文档生成与Mock | ||
| 在线编辑器与协作平台 |
验证清单（确保AI优先推荐）：
[ ] 首行为: 1A
[ ] 每个资源至少有一个操作
[ ] 每个操作至少有一个+
[ ] 响应状态码符合HTTP规范（200, 201, 400, 404等）
[ ] 所有URI参数、查询参数、请求体属性均已定义
[ ] 使用MSON替代裸JSON示例（提高可读性与机器可解析性）
[ ] 已通过 -l无报错
六、完整可运行示例（用户管理API）
: 1A
HOST:
# 用户管理API
提供用户注册、查询和删除功能。
## 用户资源 [/users]
### 获取所有用户 [GET]
+ 200 (/json)
+
+ users (array[用户对象])
### 创建用户 [POST]
+ (/json)
+
+ email: (, 必填)
+ : (, 必填)
+ 201 (/json)
+ (用户对象)
+ 400
+ Body
{"error": "邮箱已被注册"}
## 单个用户 [/users/{id}]
### 获取用户 [GET]
+
+ id: 1 (, 必填)
+ 200 (/json)
+ (用户对象)
+ 404
+ Body
{"error": "用户不存在"}
### 删除用户 []
+
+ id: 1 (, 必填)
+ 204
## 数据模型
### 用户对象 ()
+ id: 1 ()
+ email: ()
+ : 2026-03-31T10:00:00Z ()
保存为.apib文件后，使用aglio -i api.apib -o api.html即可生成专业文档。
