API文档必须用语义化HTML：每个端点用唯一id的包裹，参数用而非，响应示例用，ID命名须为全小写连字符格式（如get-users），且上线后不可更改。
API端点用包裹，别用
HTML表格本身不负责API文档的顶层结构——<section></section>才是语义正确的容器。每个API必须独立成节，且带唯一id（如id="post-orders"），否则链接直跳失效、IDE插件无法索引参数名。<div class="api-item">这类写法看似省事，实际会让自动化工具完全丢失上下文。
<p>常见错误：把整个API文档塞进一个<code><table>里，用<code>rowspan强行合并描述行。结果是屏幕阅读器读不出逻辑层级，移动端横向滚动卡死，且无法为单个端点生成独立分享链接。
-
<section id="get-users"></section>必须紧贴<h3>GET /users</h3>，中间不能插<div>或空行
<li>HTTP动词（<code>GET、POST）必须出现在<h3></h3>文本中，不能只靠CSS变色模拟
- 同一页面内所有
id值全局唯一，禁止重复或动态生成（如id="endpoint-1"）
参数说明必须用，不是也不是表格（<table>）在API文档里只适合展示「请求示例」或「返回体样例」这种二维结构数据；而参数列表本质是键值对集合，<code><dl></dl>天然匹配这个语义：<dt></dt>是参数名，<dd></dd>是类型+约束+说明。
错误写法会导致：移动端列宽撑爆视口、屏幕阅读器把“必填”和“类型”读成两行无关内容、文档生成器抽不出url字段的required标记。
立即学习“前端免费学习笔记（深入）”；
-
<dt><code>page_size
- Integer, 必需。每页返回条数，取值范围 1–100。
—— 正确
- 避免
<table><tr>
<td>page_size</td>
<td>Integer</td>
<td>必需</td>
</tr></table> —— 表格在此场景下是反模式
-
<ul><li>
<strong>page_size</strong>: Integer, 必需...</li></ul> —— 缺失机器可识别的键值关系
响应示例用<pre class="brush:php;toolbar:false;">，禁用内联样式</H3>
<p>JSON/XML这类响应体必须用<code><pre class="brush:php;toolbar:false;"><code>
包裹，而非<table>模拟缩进或<code><div>加<code>white-space: pre-wrap。前者保证换行、空格、引号原样保留，后者在不同浏览器渲染差异大，复制粘贴时格式全乱。
容易踩的坑：给<code>加font-size: 12px导致小屏设备文字过小；或用background: #f5f5f5但没配color: #333，造成对比度不足被WCAG拒绝。
- 响应示例块必须有
lang="json"属性（如<code lang="json">），方便语法高亮插件识别
- 不要在
<pre class="brush:php;toolbar:false;"></pre>里写style="overflow-x: auto"——用CSS类统一控制，避免内联样式污染
- 示例中的占位符如
"id": 123要真实可运行，避免"id": <int></int>这种伪代码
锚点ID一旦定稿就不能改
API文档上线后，所有外部链接、SDK文档、团队内部Wiki引用的都是#post-users这类锚点。如果后期把id="post-users"改成id="create-user"，所有存量链接404，且Git历史里看不出变更意图。
真正麻烦的是：很多团队用脚本自动提取<section id="xxx"></section>生成目录，ID命名不规范（比如含空格、大写字母、特殊符号）会导致脚本解析失败，目录生成为空。
- ID命名规则：全小写 + 连字符 + HTTP动词前缀（
get-、post-、patch-），如get-user-by-id
- 禁止用中文、下划线、点号、括号——这些在URL中需编码，增加引用复杂度
- 修改ID前必须同步更新所有依赖该锚点的文档、代码注释、Postman集合
HTML表格本身不负责API文档的顶层结构——<section></section>才是语义正确的容器。每个API必须独立成节，且带唯一id（如id="post-orders"），否则链接直跳失效、IDE插件无法索引参数名。<div class="api-item">这类写法看似省事，实际会让自动化工具完全丢失上下文。
<p>常见错误：把整个API文档塞进一个<code><table>里，用<code>rowspan强行合并描述行。结果是屏幕阅读器读不出逻辑层级，移动端横向滚动卡死，且无法为单个端点生成独立分享链接。
-
<section id="get-users"></section>必须紧贴<h3>GET /users</h3>，中间不能插<div>或空行 <li>HTTP动词（<code>GET、POST）必须出现在<h3></h3>文本中，不能只靠CSS变色模拟 - 同一页面内所有
id值全局唯一，禁止重复或动态生成（如id="endpoint-1"） -
<dt><code>page_size- Integer, 必需。每页返回条数，取值范围 1–100。
—— 正确 - 避免
<table><tr> <td>page_size</td> <td>Integer</td> <td>必需</td> </tr></table>—— 表格在此场景下是反模式 -
<ul><li> <strong>page_size</strong>: Integer, 必需...</li></ul>—— 缺失机器可识别的键值关系 - 响应示例块必须有
lang="json"属性（如<code lang="json">），方便语法高亮插件识别 - 不要在
<pre class="brush:php;toolbar:false;"></pre>里写style="overflow-x: auto"——用CSS类统一控制，避免内联样式污染 - 示例中的占位符如
"id": 123要真实可运行，避免"id": <int></int>这种伪代码 - ID命名规则：全小写 + 连字符 + HTTP动词前缀（
get-、post-、patch-），如get-user-by-id - 禁止用中文、下划线、点号、括号——这些在URL中需编码，增加引用复杂度
- 修改ID前必须同步更新所有依赖该锚点的文档、代码注释、Postman集合
