Generate an OpenAPI-backed HTTP API reference

[samuv]

Summary

Generate an OpenAPI-compatible reference for Mecatl's public HTTP JSON API while keeping the existing HTTP/SSE guide focused on behavior, streaming, and lifecycle semantics.

This work was split from #712 after the TypeScript SDK introduced a complete RPC catalog and mechanical parity checks against the server router and protobuf descriptors.

Current state

• internal/adapter/server/http.go is the HTTP wire source of truth, as recorded in ADR 0321.
• sdk/typescript/src/rpc-catalog.ts contains route and codec metadata used by the SDK.
• internal/adapter/server/sdk_typescript_http_routes_test.go checks the SDK catalog against the registered routes and protobuf descriptors.
• user-docs/reference/http-sse-api.md is the canonical curated HTTP/SSE guide.

The generated reference must build on these existing boundaries rather than introduce another independently maintained route table.

Scope

• Define and document how an OpenAPI-compatible artifact is generated from, or mechanically checked against, the server router and existing descriptor-backed route metadata.
• Cover every public HTTP JSON endpoint, including methods, route and query parameters, request and response schemas, authentication expectations, and status/problem responses.
• Render or link the generated endpoint reference from user-docs/reference/.
• Keep SSE framing, reconnect behavior, cursor handling, and stream lifecycle explanations in the curated HTTP/SSE guide, with links in both directions.
• Add deterministic regeneration and CI drift checks.
• Reconcile ownership with the SDK RPC catalog so adding a route does not require maintaining two unchecked contract descriptions.

Acceptance criteria

• The HTTP router remains the authoritative wire surface; no independent route table becomes a competing source of truth.
• A documented command produces a deterministic OpenAPI-compatible artifact and rendered endpoint reference.
• Every registered public JSON route is represented with its method, parameters, request and response schemas, authentication expectations, and status/problem responses.
• HTTP/SSE routes link to the curated streaming and lifecycle documentation.
• The generated reference is linked from the canonical transport and reference pages.
• CI fails when generated artifacts or checked route metadata drift from the implementation.
• task docs and task site:build pass.

Non-goals

• Generating the gRPC reference; that remains in Add a generated gRPC API reference #712.
• Replacing curated SSE lifecycle documentation with generated output.
• Changing HTTP or gRPC behavior.
• Adding a new API version.

[Sanskarzz]

Hi @samuv I would like to work on this issue after the merge of PR #1719.

I have started exploring the HTTP router, TypeScript RPC catalog, and the existing route checks. My understanding is that we need to generate an OpenAPI reference without creating another manually maintained list of HTTP routes.
Before implementing it, I would like to prepare a short plan covering:

• how the HTTP router remains the source of truth;
• how we reuse the RPC catalog and protobuf schemas;
• how authentication and error responses are documented;
• how HTTP-only and SSE endpoints are represented;
• how generated files and CI freshness checks will work.

I will keep the existing HTTP/SSE guide responsible for streaming and lifecycle explanations. I will not change HTTP or gRPC behavior.

Could you please assign this issue to me? I would also appreciate feedback on the plan before I begin the implementation.