# 覆盖范围与维护

# 覆盖范围与维护

文档站由四个事实源组合生成：

| 输出文件 | 事实源 |
| --- | --- |
| `capworks.openapi.json` | `services/api/src/routes`、`services/api/src/index.ts`、`packages/contracts` |
| `auth.openapi.json` | Better Auth 的 OpenAPI 插件与 CapWorks 认证配置 |
| `openconnector.openapi.json` | OpenConnector 自带的 OpenAPI 生成器 |
| `capworks-realtime.asyncapi.json` | 共享实时契约与实时转写协议 |

运行生成和完整检查：

```bash
bun run --cwd apps/api-docs generate
bun run --cwd apps/api-docs check
bun run --cwd apps/api-docs build
```

`check` 会重新读取源码路由，确保每个明确的 HTTP method + path 都进入 CapWorks OpenAPI；同时检查操作数量、重复 `operationId`、本地 `$ref` 和 3 条 WebSocket channel。新增路由而没有进入规范时，构建会直接失败。

业务路由中的少数动态响应目前以通用 JSON 对象展示；只要共享契约已经存在，就应在 `scripts/generate-api-specs.mjs` 中把该 operation 映射到具体类型。Provider 级 OpenConnector Action 的精细输入输出仍由其运行时按 `actionId` 动态生成。