Insert endpoint block
插入端点块
P0 写法：在编辑器里用源码 / HTML模式粘贴约定骨架，再改文案。编辑器「插入 API 块」按钮是后续增强，当前不依赖。
步骤
- 新建页（建议页名：
动词 · 路径，一端点一页）。 - 编辑器切到源码（或 HTML）模式。
- 清空默认空段落，粘贴下方「完整骨架」。
- 改：方法徽章类名、路径、
operationId、参数表、curl / fetch、响应 JSON。 - 保存后在阅读壳预览；对照示例页 获取小部件。
方法徽章类名
| 方法 | 类名 |
|---|---|
| GET | cb-api-method cb-api-method--get |
| POST | cb-api-method cb-api-method--post |
| PUT | cb-api-method cb-api-method--put |
| PATCH | cb-api-method cb-api-method--patch |
| DELETE | cb-api-method cb-api-method--delete |
必填块顺序
- 根包裹
div.cb-api（一页一个） h1操作名.cb-api-endpoint（方法徽章 + path）.cb-api-meta（可选但推荐）- 简述
p - 参数表
table.cb-api-table（有则写） - 请求示例：至少 curl，建议再给 fetch（可用
details.cb-api-fold折叠） - 响应：状态码芯片 + JSON 示例
禁止
- 不要嵌 Scalar / Swagger / Redoc / 试调表单
- 不要一页堆多个端点
- 不要用系统
/api/docs的api-method色块 - 不要把产品接口写进 /api/docs
完整骨架（复制用）
下面是与「获取小部件」同构的 HTML。粘贴后把示例字段换成你的接口即可。
HTML 源码
<!-- 酷可 API 端点页骨架 · 粘贴到 BookStack 页 HTML/源码模式 -->
<!-- 一端点一页 · 甲·浅底方章 · 仅 curl/fetch 静态示例 · 勿嵌试调器 -->
<!-- PRE 20261102apiFoldPre：Header open fold · 请求示例 collapsed fold -->
<div class="cb-api">
<h1>获取小部件</h1>
<div class="cb-api-endpoint">
<span class="cb-api-method cb-api-method--get">GET</span>
<code class="cb-api-path">/v1/widgets/<var>id</var></code>
</div>
<p class="cb-api-meta">operationId: <code>getWidget</code> · 分组: Widgets · 鉴权: Bearer Token</p>
<p>按 ID 返回单个小部件。路径参数 <code class="cb-api-param">id</code> 为资源主键；响应体字段以本文示例为准（可替换为你的 OAS 示例）。</p>
<h2>Path 参数</h2>
<table class="cb-api-table">
<thead>
<tr><th>名称</th><th>位置</th><th>类型</th><th>必填</th><th>说明</th></tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>path</td>
<td><span class="cb-api-type">string</span></td>
<td><span class="cb-api-required">必填</span></td>
<td>小部件 ID</td>
</tr>
</tbody>
</table>
<details class="cb-api-fold" open>
<summary>Header 参数</summary>
<table class="cb-api-table">
<thead>
<tr><th>名称</th><th>位置</th><th>类型</th><th>必填</th><th>说明</th></tr>
</thead>
<tbody>
<tr>
<td><code>Authorization</code></td>
<td>header</td>
<td><span class="cb-api-type">string</span></td>
<td><span class="cb-api-required">必填</span></td>
<td><code>Bearer <token></code></td>
</tr>
</tbody>
</table>
</details>
<details class="cb-api-fold">
<summary>请求示例</summary>
<div class="cb-api-example">
<span class="cb-api-example__label">curl（静态示例；本页无试调表单）</span>
<pre><code>curl -sS 'https://api.example.com/v1/widgets/wdg_42' -H 'Authorization: Bearer YOUR_TOKEN' -H 'Accept: application/json'</code></pre>
</div>
<div class="cb-api-example">
<span class="cb-api-example__label">fetch</span>
<pre><code>fetch('https://api.example.com/v1/widgets/wdg_42', {
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Accept': 'application/json'
}
}).then(r => r.json())</code></pre>
</div>
</details>
<h2>响应</h2>
<h3><span class="cb-api-status">200</span> 成功</h3>
<div class="cb-api-example">
<span class="cb-api-example__label">application/json</span>
<pre><code>{
"id": "wdg_42",
"name": "Demo Widget",
"status": "active",
"updated_at": "2026-11-02T08:00:00Z"
}</code></pre>
</div>
<h3><span class="cb-api-status cb-api-status--err">404</span> 未找到</h3>
<p>ID 不存在或不在当前鉴权范围。</p>
<div class="cb-api-example">
<pre><code>{
"error": {
"code": 404,
"message": "Widget not found"
}
}</code></pre>
</div>
</div>
这篇文档对你有帮助吗？
谢谢你的反馈！