API参数表应仅包含参数名、类型字面量、默认值、代码示例片段四列，禁用描述性文字；type须小写规范，required用true/false，路径位置需标注，description中代码值须用包裹，JSON响应须用<pre>嵌套并声明language，HTML字符必须转义，样式应作用于<table>而非。
API参数表里该包什么</H3>
<p>只包参数名、类型字面量、默认值、代码示例片段，不包说明文字或条件逻辑。比如 <code>user_id
、string、null、"active" 这些可以进 标签；但“用户唯一标识，必填”这种描述性文字不能包进去。</p>
<p>常见错误是把整个参数说明塞进 <code>，结果渲染后字体突兀、语义错乱，还影响自动化工具提取。type 列必须小写且规范：<code>boolean
不是 Boolean 或 bool；联合类型写成 string | number，别用中文顿号分隔。
-
required 列统一用 true/false，不加引号，不写“是/否”
- 路径参数要标注位置，如
path、query、header，写在 name 列末尾或 description 开头
- description 里出现的任何代码值（如
404、["read","write"]）都必须用 包裹</li>
</ul>
<H3>多行响应示例必须用 <pre class="brush:php;toolbar:false;"><code></H3>
<p>直接用 <code> 包裹 JSON 响应体或 curl 命令，换行和缩进全丢，根本没法看。正确做法是用 <pre class="brush:php;toolbar:false;"><code> 嵌套，并显式声明语言类型：</p>
<pre class='brush:json;toolbar:false;'>{
"id": 123,
"status": "success",
"data": {
"name": "test"
}
}
注意三件事：
立即学习“前端免费学习笔记（深入）”；
- 所有 HTML 特殊字符必须转义：
<div> 不能写成 <code><div>
<li><pre class="brush:php;toolbar:false;"> 默认可能横向溢出，需加 CSS 控制：比如 <code>overflow-x: auto</code> 和 <code>tab-size: 2</code></li>
<li>不要给 <pre class="brush:php;toolbar:false;"> 单独设 background 或 font-family——样式应统一作用于 <pre class="brush:php;toolbar:false;"><code> 组合</li>
</ul>
<H3>为什么不能用 <code> 模拟表格单元格样式</H3>
<p>有人给 <code> 加 padding、border、display: block，试图把它撑成“参数卡片”，这会破坏表格语义和可维护性。API 表格本质是结构化数据，不是 UI 组件。</p>
<p>问题在于：<code> 是行内元素，强行块级化后，复制粘贴时容易带多余空格或换行；更关键的是，自动化文档工具（比如 Swagger UI 解析 HTML 表格生成 mock）只认 <table> 的列结构，不认识你自定义的 <code> 样式块。</p>
<ul>
<li>固定四列：<code>name</pre>、<code>type、required、description，别合并单元格
-
name 列末尾加 ? 表示可选，比在 description 里写“非必填”更可靠
- default 值单独成列（不是塞进 description），写
false、""、null，不写“空”或“无”
容易被忽略的细节：可访问性与工具链兼容
屏幕阅读器靠 的语义识别这是代码内容，所以别用它包裹纯文本说明；CI 流程常通过正则匹配 <code>required 列的 true/false 做校验，写成 True 或 TRUE 就会失败。
最常漏掉的是 HTML 实体转义和 language 属性。比如展示一个带尖括号的 HTML 片段，不转义就直接解析成标签；没写
，语法高亮库（如 Prism.js）就无法触发对应语言规则。</p>
<p>复杂点在于：description 里嵌套的 <code> 可能含变量占位符（如 <code>{user_id}），这种要确认是否需额外转义，否则会被误解析为模板语法。
required 列统一用 true/false，不加引号，不写“是/否”path、query、header，写在 name 列末尾或 description 开头404、["read","write"]）都必须用 包裹</li>
</ul>
<H3>多行响应示例必须用 <pre class="brush:php;toolbar:false;"><code></H3>
<p>直接用 <code> 包裹 JSON 响应体或 curl 命令，换行和缩进全丢，根本没法看。正确做法是用 <pre class="brush:php;toolbar:false;"><code> 嵌套，并显式声明语言类型：</p>
<pre class='brush:json;toolbar:false;'>{
"id": 123,
"status": "success",
"data": {
"name": "test"
}
}
注意三件事：
立即学习“前端免费学习笔记（深入）”；
- 所有 HTML 特殊字符必须转义：
<div> 不能写成 <code><div> <li><pre class="brush:php;toolbar:false;"> 默认可能横向溢出，需加 CSS 控制：比如 <code>overflow-x: auto</code> 和 <code>tab-size: 2</code></li> <li>不要给 <pre class="brush:php;toolbar:false;"> 单独设 background 或 font-family——样式应统一作用于 <pre class="brush:php;toolbar:false;"><code> 组合</li> </ul> <H3>为什么不能用 <code> 模拟表格单元格样式</H3> <p>有人给 <code> 加 padding、border、display: block，试图把它撑成“参数卡片”，这会破坏表格语义和可维护性。API 表格本质是结构化数据，不是 UI 组件。</p> <p>问题在于：<code> 是行内元素，强行块级化后，复制粘贴时容易带多余空格或换行；更关键的是，自动化文档工具（比如 Swagger UI 解析 HTML 表格生成 mock）只认 <table> 的列结构，不认识你自定义的 <code> 样式块。</p> <ul> <li>固定四列：<code>name</pre>、<code>type、required、description，别合并单元格 -
name列末尾加?表示可选，比在 description 里写“非必填”更可靠 - default 值单独成列（不是塞进 description），写
false、""、null，不写“空”或“无”
容易被忽略的细节：可访问性与工具链兼容
屏幕阅读器靠 的语义识别这是代码内容，所以别用它包裹纯文本说明；CI 流程常通过正则匹配 <code>required 列的 true/false 做校验，写成 True 或 TRUE 就会失败。
最常漏掉的是 HTML 实体转义和 language 属性。比如展示一个带尖括号的 HTML 片段，不转义就直接解析成标签；没写
，语法高亮库（如 Prism.js）就无法触发对应语言规则。</p>
<p>复杂点在于：description 里嵌套的 <code> 可能含变量占位符（如 <code>{user_id}），这种要确认是否需额外转义，否则会被误解析为模板语法。
