OpenAPI Specification

Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: chengflow/openapi.yaml, chengflow/Makefile, crates/cheng-api/src/rest/routes.rs

chengflow/openapi.yaml is an OpenAPI 3.0.3 specification of the REST API, and the Makefile turns it into Swagger UI, Redoc, a Postman collection, generated SDKs, Markdown reference, and contract tests.

Read this first: the spec is a curated subset, not the whole API. It documents 28 paths — auth, workspaces, files, conversations, workflows, executions, nodes, system endpoints, and workflow-template sync — while the running server exposes considerably more, including channels, documents, tables, skills, schedules, artifacts, and code index. For anything outside those tags, the REST API overview and rest/routes.rs are authoritative.

What the spec declares

openapi: 3.0.3
info:
  title: Cheng-Workflow API
  version: 1.0.0
servers:
  - url: http://localhost:19225        # local development
  - url: https://api-staging…         # staging
  - url: https://api…                 # production
security:
  - BearerAuth: []                    # http bearer, JWT

BearerAuth applies globally, so every generated client sends the Authorization header by default. See Authentication.

Tags: auth, workspaces, files, conversations, workflows, executions, nodes, system.

The described quickstart is the real one:

1. POST /api/v1/auth/login       → token
2. POST /api/v1/workflows        → create
3. POST /api/v1/executions       → run
4. WS   /ws/executions/{id}      → subscribe

Shared parameters Offset and Limit are defined once and reused, so pagination is consistent across the documented endpoints.

Generating

make openapi        # regenerate openapi.yaml from code
make docs           # openapi + swagger + redoc + postman + sdk + markdown
make docs-validate  # lint the spec
make docs-serve     # browse at :8000
make docs-clean     # remove generated output, including openapi.yaml

make check-deps verifies cargo, npm, and docker are present; make install-tools installs utoipa-cli, @redocly/cli, openapi-to-postmanv2, and widdershins.

make docs-clean deletes openapi.yaml itself, not only the rendered output. If you have hand-edited the spec, that removes your edits.

Generation uses utoipa-cli over crates/cheng-api/src/lib.rs, so annotated handlers are the source. Handlers without annotations do not appear — which is the mechanical reason the spec is partial.

What you can generate from it

Swagger UI, Redoc, and the SDK generators run in Docker, so they need a working Docker daemon, not just Node.

The generated TypeScript client is @cheng/workflow-client, Python is cheng_workflow, Rust is cheng-workflow-client.

For a browser chat or gateway integration, prefer the hand-written SDK over a generated client: it also handles the WebSocket protocol, session mapping, and token refresh, none of which an OpenAPI generator can produce.

Contract testing

make test-api       # schemathesis against a running server
make test-postman   # newman over the generated collection

test-api runs schemathesis with all checks against http://localhost:19225, 20 generated examples per operation. It is property-based: it derives requests from the schema and checks the responses conform, so it finds the mismatches between spec and implementation that a hand-written test suite would not think to try.

Both need a running server. test-api will exercise real endpoints, so point it at a development instance, not production.

Using the spec elsewhere

# Any OpenAPI-aware client
curl -s http://localhost:19225/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"…","password":"…"}'

Import openapi.yaml into Insomnia, Bruno, or your API gateway; generate a mock server; validate requests at the edge. The spec is a plain file with no ChengOS-specific extensions.

Keeping it honest

The spec is checked in, which means it can drift from the code. Three habits keep it useful:

1. Regenerate rather than hand-edit. make openapi reads the annotated handlers; a manual edit is lost on the next regeneration and, worse, may not match reality in the meantime.
2. Run make docs-validate after regenerating — the Redocly linter catches structural problems before a client generator turns them into broken code.
3. Run make test-api against a development server when you change a documented handler. That is the only step that compares the spec with the running system.

Next steps

• REST API Overview — the full endpoint surface.
• Authentication — the BearerAuth scheme in practice.
• WebSocket API — the half OpenAPI cannot describe.