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