API 参数表应使用语义清晰的 ，固定四列（name、type、required、description），禁用合并单元格，type 小写规范，required 统一为 true/false，说明中代码用 包裹，条件必填在 description 中明确，响应式优先精简列而非 CSS 强撑，避免客户端 JS 动态渲染，name 需标注参数位置（如 query/path）。
HTML 表格怎么写才适合放 API 参数
直接用 <table> 没问题，但很多人一上来就套样式、加复杂 class，结果参数对不齐、语义混乱，文档一更新就崩。API 参数表的核心是「可读性 + 可维护性」，不是视觉效果。
<p>关键点：列必须固定含义（参数名、类型、必填、说明），行之间不能有逻辑嵌套，所有 <code>type 和 required 值要能一眼扫完。
- 用
<thead> 明确标出四列：<code>name、type、required、description - 避免合并单元格（
rowspan/colspan）——参数增减时极易错位 -
type列统一小写，如string、number、boolean、object；复杂类型写成Array<string></string>而非 “字符串数组” - 说明文字里出现的代码片段，比如默认值
null或示例值"active"，必须用<code>包裹 - 统一用
true/false，小写，无引号 - 如果某参数既可选又可空，不要写
false就完事，得在description里补一句：“默认为null，传空字符串视为有效值” - 遇到条件必填（如 “当
mode为"custom"时必填”），required列写false，但 description 必须明确条件，不能藏在备注里 - 把
description列拆出来，用<details></details>折叠（注意：IE 不支持，但现代文档站基本不考虑 IE） - 删掉“来源”“示例值”等非常规列——这些应该放在表格下方的独立代码块里，用
<pre class="brush:php;toolbar:false;"><code></code> 展示请求体</pre> - 如果必须保留多列，优先合并
type和required成一列，格式为string (required)或number? (optional) - SEO 友好性归零——爬虫看不到参数，搜索“
api_name参数列表”根本搜不到 - 首次渲染白屏时间变长，尤其参数多时，JS 执行完才出表
- 如果 JSON 结构字段名和 HTML 列不一致（比如后端返回
is_required，你硬映射成required），改错一个字段，整张表required全乱
为什么 required 列不能写“是/否”而要写 true/false
因为前端文档常被自动化工具消费（比如 Swagger UI 解析 HTML 表生成 mock），也方便后续用 JS 抓取判断逻辑。写中文“是”容易和说明文字混淆，且无法被脚本可靠识别。
更实际的问题是：有人写 ✅/❌、✔/✘、Y/N，这些在复制粘贴、正则匹配、CI 检查时全都会挂。
立即学习“前端免费学习笔记（深入）”；
表格响应式差？别用 CSS 强撑，先砍列
移动端看参数表最痛苦的不是字小，而是横向滚动+错行。很多团队强行给 <table> 加 <code>overflow-x: auto，结果用户划两下就找不到哪列对应哪行了。
真实解法不是调样式，是精简信息密度：
用 JS 动态渲染参数表？小心 DOM 更新时机
有人图省事，用 fetch 拉 JSON 参数定义，再用 innerHTML 拼表格。看起来灵活，但实际埋了三个坑：
真要动态，建议服务端渲染或用静态站点生成器（如 Docsify/VitePress）预编译，而不是靠客户端 JS 现拼。
最常被忽略的一点：参数表里的 name 是 URL 路径参数还是 query 参数，必须在表头或首行加注释，比如 name 列标题写成 name (query) 或 name (path) —— 这个细节，90% 的人上线后才发现对接方理解反了。
