Copy page

维护与部署

覆盖范围与维护

覆盖范围与维护

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

输出文件	事实源
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	共享实时契约与实时转写协议

运行生成和完整检查：

Code
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 动态生成。