[Docs] Automate API reference generation from OpenAPI / route catalog (stop hand-editing)

Summary

Today website/docs/api/apiserver.md and parts of website/docs/api/router.md are hand-maintained. When apiserver routes change (routes_catalog.go, handlers, OpenAPI generation), the website docs drift — see #2772.

We already have a live machine-readable source of truth:

• Route catalog: src/semantic-router/pkg/apiserver/routes_catalog.go
• Live OpenAPI: GET /openapi.json (generateOpenAPISpec() in pkg/apiserver/openapi_spec.go)
• Live Swagger UI: GET /docs
• Discovery index: GET /api/v1

Goal: stop humans from editing API reference markdown for endpoint tables / request-response shapes. Generate those pages (or embed OpenAPI) from the catalog/OpenAPI, and fail CI when docs are stale.

Motivation

• Endpoint docs go stale quickly (eval, recipes, outcomes, memory, vector stores, Idempotency-Key, etc.).
• Contributors update Go routes but forget website docs.
• First-time users get incomplete/outdated curl examples.
• Manual “refresh the API reference” PRs (#2772) do not scale.

Proposed approach

Treat code + OpenAPI as source of truth; website markdown becomes generated or thin wrappers.

Phase 1 — Export OpenAPI artifact in CI/build

1. Add a Make target, e.g. make api-docs-openapi, that dumps the apiserver OpenAPI JSON/YAML to something like:
   • website/static/openapi/apiserver.openapi.json
   • (optional) docs/generated/apiserver.openapi.json
2. Prefer generating from the same generateOpenAPISpec() / route catalog used at runtime (unit-testable; no need to boot full router if possible).
3. CI check: regenerated file must match committed artifact (git diff --exit-code).

Phase 2 — Generate website API reference from OpenAPI

Pick one established path (recommend evaluating these):

Option	Fit	Notes
Docusaurus OpenAPI (docusaurus-plugin-openapi-docs / Redocusaurus)	High	Renders interactive reference from OpenAPI; common for Docusaurus sites
Redocly (@redocly/cli build-docs)	High	Static HTML/MD from OpenAPI; good linting (redocly lint)
Custom generator from route catalog → Markdown tables	Medium	Reuses EndpointMetadata; good for compact tables + curated curl snippets
Swagger Codegen / openapi-generator	Lower for docs	Better for SDKs than narrative docs

Recommended direction:

1. Enrich OpenAPI with request/response schemas + examples where missing (today some paths are thin).
2. Generate website/docs/api/apiserver.md (or a generated sibling like apiserver.generated.md) from OpenAPI.
3. Keep a small hand-written intro only (ports, auth overview, “how to run locally”) in a non-generated file that includes/embeds the generated reference.
4. Mark generated files with a header: DO NOT EDIT — generated by make api-docs-generate.

Phase 3 — CI automation on API surface changes

When PRs touch:

• src/semantic-router/pkg/apiserver/**
• ExtProc public replay paths if documented (router_replay*)
• OpenAPI generation code

Then CI should:

1. Regenerate OpenAPI + Markdown (or fail if contributor didn’t run make api-docs-generate)
2. Optionally open/require a docs update via the stale-diff check
3. Optionally run redocly lint / OpenAPI contract tests

Also add a pre-commit or agent-harness hook for apiserver path changes → remind/run api-docs-generate.

Phase 4 — Router data-plane docs

website/docs/api/router.md covers Envoy :8801 (chat/completions, responses, router_replay). That surface is not fully in apiserver OpenAPI today.

Options:

• Extend OpenAPI (or a second OpenAPI doc) for ExtProc HTTP APIs (/v1/router_replay*, etc.)
• Or keep a thin hand-written data-plane page that embeds generated sections where possible

Non-goals (initially)

• Auto-writing long narrative tutorials
• Replacing Swagger UI at :8080/docs (keep it; website should align with it)
• Generating client SDKs in the first PR

Acceptance criteria

• OpenAPI JSON/YAML can be generated offline via Make from the route catalog / generateOpenAPISpec
• Website apiserver API reference tables/schemas are generated (or rendered from OpenAPI), not hand-edited
• Generated files carry a clear “do not edit” banner
• CI fails if API routes change but generated docs/OpenAPI are not updated
• Docs still include first-time-user curl examples (either generated from OpenAPI examples or a small curated overlay)
• Document the contributor workflow: change routes → make api-docs-generate → commit artifacts

Suggested first PR scope

1. make api-docs-openapi + commit website/static/openapi/apiserver.openapi.json
2. CI drift check
3. Replace hand-maintained endpoint index in apiserver.md with generated content (or OpenAPI plugin page)
4. Follow-up: enrich OpenAPI examples (including Idempotency-Key on POST /v1/router/outcomes)

Related

• #2772 — manual API reference refresh (symptom of missing automation)
• Live sources: /openapi.json, /docs, routes_catalog.go, openapi_spec.go

Labels (suggested)

documentation, enhancement, good first issue (for Phase 1 only) / help wanted