OpenAPI 规范与代码生成

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow/openapi.yaml、chengflow/Makefile、crates/cheng-api/src/rest/routes.rs

chengflow/openapi.yaml 是 REST API 的 OpenAPI 3.0.3 规范，Makefile 能把它变成 Swagger UI、Redoc、Postman 集合、生成的 SDK、Markdown 参考手册以及契约测试。

先读这一条：该规范是一个精选子集，不是整套 API。 它描述了 28 条路径——认证、工作区、文件、会话、工作流、执行、节点、系统接口，以及工作流模板同步——而运行中的服务器暴露的接口要多得多，包括渠道、文档、表格、技能、定时任务、产物和代码索引。这些标签之外的内容，以 REST API 总览和 rest/routes.rs 为准。

规范里声明了什么

openapi: 3.0.3
info:
  title: Cheng-Workflow API
  version: 1.0.0
servers:
  - url: http://localhost:3000        # 本地开发
  - url: https://api-staging…         # 预发布
  - url: https://api…                 # 生产
security:
  - BearerAuth: []                    # http bearer，JWT

BearerAuth 是全局生效的，因此所有生成出来的客户端默认都会带上 Authorization 请求头。见认证。

标签：auth、workspaces、files、conversations、workflows、executions、nodes、system。

其中描述的快速开始就是真实流程：

1. POST /api/v1/auth/login       → 令牌
2. POST /api/v1/workflows        → 创建
3. POST /api/v1/executions       → 运行
4. WS   /ws/executions/{id}      → 订阅

共享参数 Offset 和 Limit 只定义一次并复用，因此已文档化接口之间的分页是一致的。

生成

make openapi        # 从代码重新生成 openapi.yaml
make docs           # openapi + swagger + redoc + postman + sdk + markdown
make docs-validate  # 校验规范
make docs-serve     # 在 :8000 浏览
make docs-clean     # 删除生成产物，包括 openapi.yaml

make check-deps 检查 cargo、npm 和 docker 是否存在；make install-tools 安装 utoipa-cli、@redocly/cli、openapi-to-postmanv2 和 widdershins。

make docs-clean 会删掉 openapi.yaml 本身，不只是渲染产物。如果你手工改过规范，那些改动会一并消失。

生成使用 utoipa-cli 处理 crates/cheng-api/src/lib.rs，因此加了注解的处理器才是来源。没加注解的处理器不会出现——这正是规范不完整的机械原因。

能从它生成什么

Swagger UI、Redoc 和 SDK 生成器都跑在 Docker 里，因此需要可用的 Docker 守护进程，而不只是 Node。

生成的 TypeScript 客户端叫 @cheng/workflow-client，Python 是 cheng_workflow，Rust 是 cheng-workflow-client。

如果做的是浏览器对话或网关集成，请优先用手写的 SDK 而不是生成的客户端：它还处理 WebSocket 协议、会话映射和令牌刷新，而这些都是 OpenAPI 生成器做不出来的。

契约测试

make test-api       # 用 schemathesis 打一个运行中的服务器
make test-postman   # 用 newman 跑生成的集合

test-api 以全部检查项运行 schemathesis，目标是 http://localhost:3000，每个操作生成 20 个样例。它是基于属性的：从 schema 推导请求并检查响应是否符合，因此能发现规范与实现之间那些手写测试根本想不到去试的错位。

两者都需要服务器在运行。test-api 会真的打真实接口，所以请指向开发实例，而不是生产环境。

在别处使用这份规范

# 任何理解 OpenAPI 的客户端
curl -s http://localhost:3000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"…","password":"…"}'

把 openapi.yaml 导入 Insomnia、Bruno 或你的 API 网关；生成 mock 服务；在边缘做请求校验。这份规范就是一个普通文件，没有 ChengOS 特有的扩展。

让它保持诚实

规范是被提交进仓库的，这意味着它可能与代码漂移。有三个习惯能让它保持有用：

1. 重新生成，不要手改。 make openapi 读取带注解的处理器；手工改动会在下次生成时丢失，更糟的是，在此期间它可能与现实不符。
2. 生成后跑 make docs-validate——Redocly 的 linter 会在客户端生成器把结构问题变成坏代码之前先抓住它们。
3. 改动已文档化的处理器后，对着开发服务器跑 make test-api。 这是唯一一步真正把规范与运行中的系统做比对的操作。

下一步

• REST API 总览——完整的接口面。
• 认证——BearerAuth 在实践中的样子。
• WebSocket API——OpenAPI 描述不了的那一半。