api文档应使用语义化html：每个api用带唯一id的包裹，标题含http动词和路径，参数用定义，代码用标记，示例需最小可运行，charset、lang、base标签须准确配置，锚点id严禁变更。
直接用 HTML 写 API 文档，核心不是堆砌标签，而是让结构能被开发者一眼看懂、机器（如文档生成器或 IDE）能准确提取、浏览器能无障碍访问。关键在语义化分层 + 可定位锚点 + 无歧义的参数标记。
怎么组织 API 概述与详情区块
别用 <div class="api-section"> 这类泛化容器——它不带语义，也不利于自动化解析。每个 API 必须包裹在独立的 <code><section></section> 中，并配唯一 id（如 id="get-user"），方便链接直跳和工具索引。
-
<section id="get-user"></section>是必须的，不能用<div> 替代<li> <code><h2></h2>或<h3></h3>标题必须紧贴在<section></section>开头，且文字要含方法名和 HTTP 动词，例如<h3>GET /users/{id}</h3> - 描述、参数、返回值等子项用
<dl></dl>（定义列表）比<ul></ul>更准确：每个<dt></dt>是字段名，<dd></dd>是说明，天然表达“键-值”关系 - 错误写法：
<table><tr> <td>url</td> <td>String - 请求地址</td> </tr></table> - 正确写法：
<dl> <dt><code>url- String，必需。请求的目标 URL。
<code>必须包裹参数名、类型、状态（如required）、HTTP 状态码（如200）等所有代码级标识，否则无法被语法高亮或抽取工具识别- 只保留必要依赖：比如用
fetch就别写axios的 import；用curl就写纯命令行，不加 shell 提示符（$） - 路径和占位符要明确：URL 中的
{id}必须用花括号，不要写成123或<id></id>；JSON 示例中的字符串值必须加双引号，数字不加引号 - 避免出现
// ... 其他逻辑这类模糊省略——要么全写，要么用注释标明删减点，例如// ↓ 此处省略错误处理逻辑 -
<meta charset="UTF-8">必须出现在<title></title>之前，哪怕只差一行，某些旧版 Postman 加载时也会解码失败 -
影响屏幕阅读器对「POST」「404」等术语的发音，也影响部分 IDE 的语言服务自动补全（比如 VS Code 的 REST Client 插件会根据lang切换提示文案） - 如果文档部署在非根路径（如
/docs/api/），<base href="/docs/api/">必须加在里，否则示例中的相对路径./schemas/user.json会 404
参数表为什么必须用 <dl></dl> 而不是表格
表格（<table>）在屏幕阅读器中读取顺序混乱，且移动端容易横向溢出；而 <code><dl></dl> 天然支持语义化导航，IDE 插件也能通过 <dt></dt> 的文本内容匹配到对应参数。
<pre class="brush:php;toolbar:false;"><code></code> 块里该写什么、不该写什么</pre>
示例代码块不是用来炫技的，目标是让开发者复制粘贴后能跑通。重点在于最小可运行上下文，而非完整项目结构。
为什么 lang 和 charset 错一位，API 文档就可能失效
API 文档常被 curl、Postman、VS Code REST Client 直接加载为 raw HTML，若字符编码错乱，中文参数说明变成乱码，或 content-type: application/json 被截断，调用方根本没法理解字段含义。
最易被忽略的是锚点稳定性：一旦上线，id="post-login" 就不能改成 id="login-endpoint"，否则所有外部文档、博客、Slack 消息里的直链全部失效。API 文档的 HTML 结构，本质是契约，不是草稿。
