API文档应一级<section>划分功能域，二级用<article>封装单接口，避免<section>嵌套过深；示例与错误码用<details>折叠，警告信息用<aside aria-label>标注，导航须含真实链接。
用 <section> 划分 API 模块时，别套嵌太深
API 文档里常见把每个接口塞进一个 <section>，但容易忽略语义层级：如果整个文档是“用户管理 API”，那顶层 <section> 应该对应“用户管理”这个逻辑模块，而不是每个 GET /users 都独立一层。嵌套超过三层（比如 <section> → <section> → <section>）会让屏幕阅读器混乱，也削弱了大纲生成效果。
实操建议：
- 一级
<section>对应功能域（如“认证”“订单”“Webhook”） - 二级用
<article>包裹单个接口（它语义更准：一个可独立分发、复用的 API 单元） - 避免在
<section>里再套<section>来描述请求体字段——改用<dl>或带role="region"的<div>
<details> + <summary> 适合折叠示例和错误码
API 文档里大量请求/响应示例会拉长页面，但全收起来又影响快速扫描。原生 <details> 是轻量解法，比 JS 折叠更可靠，且支持键盘展开（Enter 或 Space）。
注意点：
立即学习“前端免费学习笔记（深入）”；
-
<summary>里别放复杂 HTML；纯文本最稳，比如<summary>curl 示例</summary> - 默认展开用
open属性：<details open>，但别对所有示例都加——首屏关键示例开，其余关 - 错误码表格建议每个
<tr>外包一层<details>，方便逐条展开看详情，而非整表滚动
<details>
<summary>200 OK 响应示例</summary>
<pre>{"id": 123, "email": "user@example.com"}</pre>
</details>
<aside> 放警告、兼容性说明，别放核心参数表
<aside> 的语义是“与主内容相关但可独立存在”的旁注，适合放 Deprecated 标记、Rate limit: 100/min、或 仅企业版支持 这类补充信息。但它不是侧边栏容器——别用它来布局参数列表或请求头表格。
常见误用：
- 把
Query Parameters表格塞进<aside>→ 应该用<section>或直接<table>，它是接口定义的主干部分 - 多个
<aside>堆在一起 → 合并成一个，用<h4>分段，否则辅助技术会当成多个离散提示 - 没配
aria-label→ 加上，比如<aside aria-label="兼容性说明">，不然读屏软件只报“aside”
用 <nav> 做 API 目录时，必须含真实链接
很多文档站把左侧导航写成 <nav><ul><li>用户 API</li></ul></nav>，但 <li> 里没 <a> ——这违反 <nav> 的语义要求（必须是导航到其他资源的链接集合）。结果是：大纲工具识别失败，键盘用户无法用 Tab 跳转，SEO 也丢权重。
正确做法：
- 每个菜单项必须是
<a href="#users">用户 API</a>或指向独立页面的链接 - 锚点链接要确保目标元素有
id，且不重复（<section id="users">） - 如果目录是 JS 动态加载的，得手动补
role="navigation"并保证焦点管理，原生<nav>更省事
<section> 和 <article> 的混用边界：一个接口的全部信息（请求、响应、参数、示例）是一个 <article>；而“用户相关接口”这个集合才是 <section>。错位一两次看不出问题，整站批量套错，后续做自动化大纲提取或无障碍审计就会卡住。 
