Handbook

Builders — OpenAPI rollup (derived)

Forge Lenses ships a non-authoritative OpenAPI snapshot regenerated from docs/generated/api-routes.json:

Topic · Updated

  • docs/generated/openapi.json — emits one path bucket per discrete route signature in the collector (method inventory, not exhaustive request/response models).
  • Generator — generator/export_openapi.py (scripts/check-docs.sh rewrites the file whenever api-routes.json changes).

Automation keeps this aligned with check-generated-openapi-fresh.py: stale committed JSON fails CI after generator/export_openapi.py tweaks.

Treat the OpenAPI artefact as a navigator alongside the handbook. Runtime truth remains lenses/serve.py, JSON Schemas under docs/schemas/, and the maintained HTTP appendix.

Builder API documentation tree

How derived OpenAPI sits alongside handbook HTTP tables, JSON Schemas, and runtime truth for builders.

  1. Process flowThe builder-facing path from route inventory to reviewable API documentation.
  2. Root / intakeRoute inventory and handbook prose as the shared intake surface.
  3. branch AHandbook HTTP tables listing method inventories per route family.
  4. branch BJSON Schemas defining request and response shapes where they exist.
  5. branch CDerived openapi.json as a non-authoritative route navigator.
Derived OpenAPI is a sibling to handbook tables and schemas, not a second server implementation

Stable route families referenced in reviewer contracts

The API documentation contracts in docs/strategy/api-family-contracts.json anchor prose coverage for orchestration jobs. Mention these prefixes prominently when you cite HTTP behaviour anywhere in handbook + builder corpus:

Family Typical prefix Companion docs
Docs Health /api/docs-health (/api/docs-health/summary, /api/docs-health/work-items, …) Docs Health Lenses
Wizard + blueprints sessions /api/blueprints plus /api/blueprints/wizard/* (session persistence) Wizard overview, wizard-session.schema.json
Repo + workspace overlays /api/repo (status, branches, artefacts behind Studio overlays) Schemas and API (builders)
LLM tooling /api/llm (/api/llm/settings, probes, diagnostics) LLM and AI setup (Studio consumes these routes.)
Forge Fleet mesh bridges /api/fleet (pooling hooks that pair with Forge Fleet admins) LLM setup + enterprise fleet chapter
Local auth /api/auth (/api/auth/status, GitHub PAT exchange, logout, OIDC callbacks) Builders — auth & safety, Security — local-first

When a tier is labelled experimental upstream and no schema exists yet, add the escape token documented in api-family-contracts.json (for example SCHEMA_EXEMPT_api_blueprints in Markdown) beside the handbook paragraph explaining why automation must skip assertions.

Workflow

python3 generator/collect_lenses_api_routes.py --output docs/generated/api-routes.json
python3 generator/export_api_routes_docs.py      # snapshots Markdown + JSON
python3 generator/export_openapi.py              # derives openapi.json
python3 scripts/check-generated-openapi-fresh.py # drift gate vs committed file

Verify

Follow Builders — schemas for pytest tests/test_docs_schemas.py and keep JSON examples paired whenever you touch request/response bodies.