API文档应一级划分功能域，二级用封装单接口，避免嵌套过深；示例与错误码用折叠，警告信息用标注，导航须含真实链接。
用
API 文档里常见把每个接口塞进一个 ，但容易忽略语义层级：如果整个文档是“用户管理 API”，那顶层 应该对应“用户管理”这个逻辑模块，而不是每个 GET /users 都独立一层。嵌套超过三层（比如 → → ）会让屏幕阅读器混乱，也削弱了大纲生成效果。
实操建议：
- 一级
对应功能域（如“认证”“订单”“Webhook”） - 二级用
或指向独立页面的链接 - 锚点链接要确保目标元素有
，且不重复（） - 如果目录是 JS 动态加载的，得手动补
role="region"更省事
和
200 OK 响应示例
{"id": 123, "email": "user@example.com"}
