用 <details>+<summary> 实现无 JS 可折叠 API 文档，语义化、SEO 友好、键盘可操作；参数表需含类型/必填/示例三列，错误响应附真实 JSON 示例，响应体 JSON 应缩进2格并语法高亮。
用纯 HTML + CSS 实现可折叠的接口列表
不需要框架也能做出清晰、可交互的 API 文档页，关键是把每个接口包装成独立的 <details> 块。现代浏览器（Chrome 12+、Firefox 49+、Safari 12.1+）原生支持，不用 JS 就能展开/收起请求示例、响应体、参数说明。
常见错误是直接堆 <div> 加 JS 控制显隐——既增加维护成本，又在无 JS 环境下完全不可读。而 <details> + <summary> 天然语义化，SEO 友好，打印时默认展开，还支持键盘操作（空格/回车切换）。
实操建议：
- 每个接口用一个
<details>包裹，<summary>里放方法名、路径、简要描述，例如GET /api/users - 内部用
<pre><code>显示curl示例和 JSON 响应，注意给<code>加class="bash"或class="json"方便后续加语法高亮 - 避免在
<summary>里塞太多文字，否则折叠按钮变宽难点击；描述性内容移到展开区内部 - 用 CSS 控制
details[open] summary::after替换默认箭头，更统一（比如改成▼），但别删掉原生行为
参数表格必须带类型、必填、示例三列
开发者最常卡在“这个字段到底能不能为空”“传字符串还是数字”，文档里光写 user_id 没用，得明确约束。
立即学习“前端免费学习笔记（深入）”；
错误做法是用段落罗列参数，或者只写“参数见下方 JSON”。正确结构是语义化 <table>，表头固定为：参数名、类型、是否必填、说明、示例。其中 类型 列必须精确到 string / integer / boolean / array<string>，不能写“文本”或“数字”。
实操建议：
-
是否必填列统一用 ✅ / ❌，别用“是/否”或“Y/N”，视觉扫描更快 - 嵌套字段（如
address.city）单独成行，缩进用padding-left，别靠换行符对齐 - 如果参数有枚举值（如
status: "active" | "inactive"），在示例列直接写全，不要藏在“说明”里 - 避免合并单元格（
rowspan），会破坏屏幕阅读器解析顺序
状态码和错误响应不能只写 HTTP 数字
看到 400 Bad Request 这一行，开发者不知道错在哪——是 token 过期？body 缺字段？还是 JSON 格式错了？必须给出真实错误响应体示例。
典型坑是只列状态码表格，却不说明触发条件。比如 422 Unprocessable Entity 在不同接口含义不同：用户注册时可能是邮箱格式错，上传文件时可能是 file_size 超限。
实操建议：
- 每个接口下单独设“错误响应”小节，用
<details>折叠，避免干扰主流程 - 每种错误码配一个
<pre><code>块，内容是真实返回的 JSON，包含error_code、message、field（如有）等字段 - 在错误示例上方用短句说明触发场景，例如：“当
email字段缺失时返回” - 不要省略
Content-Type: application/json响应头说明，有些客户端（如早期 axios）依赖它判断解析方式
响应体 JSON 要做最小化格式化 + 关键字段高亮
直接贴压缩后的 JSON（如 {"id":1,"name":"a","tags":[]}）几乎无法阅读。但过度美化（加动画、点击展开子节点）又偏离静态文档定位。
真正有效的做法是：服务端生成时就做两件事——缩进 2 空格、控制嵌套深度不超过 3 层；前端用 CSS 对 string、number、boolean、null 做颜色区分，并对高频字段（如 id、created_at、status）加 font-weight: bold。
实操建议：
- 用 Python 的
json.dumps(obj, indent=2, ensure_ascii=False)或 Node.js 的JSON.stringify(obj, null, 2)生成示例，别手敲 - CSS 高亮靠
<code>内部的<span class="json-string">这类标签，而不是正则匹配——后者容易误标（比如字符串里的冒号） - 数组长度超过 5 项时，在示例里用
"... (3 more items)"截断，注明“实际返回全部数据”，避免文档过长 - 如果响应含二进制字段（如
avatar_base64），示例中替换为"<base64 string of 1234 bytes>"，不贴真实值
最易被忽略的是响应时间字段的单位和精度——写 response_time: 123 不如写 response_time_ms: 123，否则前端可能误以为是秒。同理，时间戳必须标注是 Unix timestamp 还是 ISO 8601 字符串，哪怕你项目里全用一种，也得在文档顶部统一声明。
