Skip to content

Describe the Gateway API with utoipa (parallel to #7) - #11

Open
sykosyber wants to merge 1 commit into
cppalliance:masterfrom
sykosyber:mateo/gateway-openapi-utoipa
Open

sykosyber wants to merge 1 commit into
cppalliance:masterfrom
sykosyber:mateo/gateway-openapi-utoipa

Conversation

@sykosyber

@sykosyber sykosyber commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Andrew asked on #7 whether a third-party crate already provides this, so we would not have to maintain it. This describes the same API with utoipa, so the two approaches can be compared side by side. Only one of the two should land.

What it does

  • #[utoipa::path] attributes on the 13 public handlers and ToSchema derives on their wire types.
  • Test-only OpenApi derives collect them; the speech crate exports its two handlers through a public SpeechApi. build_router is not changed, and every route keeps its path.
  • The document is committed at crates/gateway/app/openapi.json. A test regenerates it and fails on any difference. BLESS_OPENAPI=1 cargo test -p gateway --lib openapi rewrites it.
  • A coverage test holds the document to the route registry, and a validity test checks it against the vendored OAS 3.1 schema.

Same as #7

Paths, operations, status codes, media types, error-code lists and required fields are the same in the two committed documents.

Trade-off

Not done

Also in this commit

  • The route registry gains the two speech routes and the five config UI assets, as in Generate and pin an OpenAPI 3.1 description of the Gateway #7: seven more debug route mounted lines, no response changes.
  • One CI step runs the OpenAPI tests without default features, as in Generate and pin an OpenAPI 3.1 description of the Gateway #7.
  • Three typed replies replace json! values with the same output, each with a test.
  • session_error moved to realtime/route-errors.rs to keep route.rs under the 500-line limit.
  • boot_speech_tests.rs: realtime_upgrade_status is now compiled only with config-ui. That unused-function warning in the stt-only build is already on master.

Checks

Run locally on Windows on this change, on master at fe136b4: fmt, clippy, nextest (1963 passed, 54 skipped), the headless build, the OpenAPI tests without default features and with only stt, rustdoc, cargo deny, xtask tidy, build-xtask tests, the UI typecheck and tests. CI passed on fb60a7f, Linux and Windows.

Plan: vibe/2026-11/2026-11-12-1-gateway-openapi-utoipa.md

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 7da8d66e-f4fd-4387-90ae-56ea95085773
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@sykosyber
sykosyber marked this pull request as ready for review November 13, 2026 17:15
@greptile-apps

greptile-apps Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge, with the previous non-blocking provider-error description issue still open.

Findings

  1. P2 Provider errors are described incorrectly ▶
Fix with agent prompt
### Issue 1
crates/gateway/app/src/relay.rs:101-104
The explicit `403` response says there is no body, but a provider's `403` returns JSON with `error.code = upstream_client_error`. OpenAPI uses this explicit response instead of the `4XX` fallback, so generated clients can discard the error details.

The same overlap leaves `upstream_client_error` out of the explicit `400`, `401`, `404`, and `429` code lists. Include provider failures in each affected response, including the JSON body for `403`, and regenerate the document. This also applies to the speech and web search descriptions.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds a committed OpenAPI 3.1 description generated with utoipa.

  • The Gateway's public routes and wire types now produce a committed OpenAPI description.
  • Health, voice, and cache replies now use named types with the same JSON output.
  • Realtime error mapping lives in its own file, and a speech test helper is feature-gated.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Handler attributes and wire types] --> B[utoipa document]
  B --> C[Add markers and widen overlapping unions]
  C --> D[Compare with committed openapi.json]
  C --> E[Check routes and feature builds]
  C --> F[Check OpenAPI validity]
Loading

Reviews (2) · Last reviewed commit: "Describe the Gateway API with utoipa" · Reviewed by Greptile

Comment on lines +101 to +104
(status = 403, description = "No body. The host wall refused a request whose authority is not the bound loopback socket."),
(status = 404, description = "The request named a model with no `[[model]]` entry.", body = ErrorEnvelope),
(status = 429, description = "The model's queue turned the request away at capacity.", body = ErrorEnvelope),
(status = "4XX", description = "The upstream backend answered with this client error status, passed through.", body = ErrorEnvelope),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Provider errors are described incorrectly

The explicit 403 response says there is no body, but a provider's 403 returns JSON with error.code = upstream_client_error. OpenAPI uses this explicit response instead of the 4XX fallback, so generated clients can discard the error details.

The same overlap leaves upstream_client_error out of the explicit 400, 401, 404, and 429 code lists. Include provider failures in each affected response, including the JSON body for 403, and regenerate the document. This also applies to the speech and web search descriptions.

Prompt To Fix With AI
This is a comment left during a code review.
Path: crates/gateway/app/src/relay.rs
Line: 101-104

Comment:
**Provider errors are described incorrectly**

The explicit `403` response says there is no body, but a provider's `403` returns JSON with `error.code = upstream_client_error`. OpenAPI uses this explicit response instead of the `4XX` fallback, so generated clients can discard the error details.

The same overlap leaves `upstream_client_error` out of the explicit `400`, `401`, `404`, and `429` code lists. Include provider failures in each affected response, including the JSON body for `403`, and regenerate the document. This also applies to the speech and web search descriptions.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

The Gateway had no machine-readable description of its API. This adds an OpenAPI 3.1 document that utoipa builds from attributes on the 13 public handlers and derives on their wire types, and commits it beside the gateway crate. A test regenerates it and fails when the committed copy differs, a coverage test holds it to the route registry, and a validity test checks it offline against the official OAS 3.1 schema.

- `crates/gateway/app/src/openapi.rs` lists the handlers in test-only `OpenApi` derives and adds the security schemes. `build_router` is untouched, and each attribute binds its registry constant's path.
- `crates/gateway/app/src/openapi/markers.rs` adds the `x-runvil-*` markers utoipa's attributes cannot carry, widens two `oneOf` unions whose branches overlap to `anyOf`, and sets the loading 503's `Retry-After` to the constant 5.
- `utoipa` is a normal dependency of six crates and `jsonschema` a dev-dependency. The release binary carries the derives but never builds the document.
- `crates/gateway/stt/api/src/realtime/route-errors.rs` takes `session_error` out of the route file, which the new attribute pushed past 500 lines.
- `crates/gateway/app/src/registry.rs` now lists the two speech routes and the five config UI assets, adding seven debug `route mounted` lines. No status, header, or body changes.
- `HealthReply`, `VoicesReply`, and `CacheDeletedReply` replace `json!` replies and serialize byte for byte as before. `ErrorEnvelope` and `CacheReadyReply` name bodies the server writes as JSON literals, and `TranscriptionUpload` and `RealtimeIntent` name inputs the handlers parse by hand; none is ever built.
- `ERROR_CODES` is written by hand, and no test checks that a declared status or error code is one the route can return or that a real response matches the document. Enums lose their per-variant descriptions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Plan: vibe/2026-11/2026-11-12-1-gateway-openapi-utoipa.md
@sykosyber
sykosyber force-pushed the mateo/gateway-openapi-utoipa branch from 6d5d8e4 to fb60a7f Compare November 16, 2026 18:14
@sykosyber
sykosyber requested review from awheeler294 and a balanced review from Copilot November 16, 2026 18:14

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Exact-status OpenAPI entries override 4XX, omitting valid upstream_client_error codes and incorrectly documenting upstream 403 responses as bodyless across relay, speech, and web search.

1 open issue
What changed in this PR

This PR offers a utoipa-based alternative to #7 for describing the Gateway’s public API in OpenAPI 3.1. It derives the description from handler annotations and wire types while preserving route paths and response formats.

Changes:

  • Annotates 13 public operations and their schemas, with post-processing for Gateway extensions.
  • Adds document drift, route coverage, feature-shape, and offline validity checks.
  • Expands the route registry and introduces three typed replies with serialization checks.
File Description
vibe/​2026-11/​2026-11-12-1-gateway-openapi-utoipa.md Records the design, trade-offs, and verification plan.
crates/​gateway/​web-search/​src/​service.rs Derives search request and response schemas.
crates/​gateway/​web-search/​Cargo.toml Adds utoipa.
crates/​gateway/​stt/​api/​src/​realtime/​route.rs Documents the WebSocket handshake and names its path.
crates/​gateway/​stt/​api/​src/​realtime/​route-errors.rs Holds the relocated session-error mapping.
crates/​gateway/​stt/​api/​src/​realtime/​query.rs Adds the schema-only realtime intent enum.
crates/​gateway/​stt/​api/​src/​realtime.rs Exposes the route module and path constant.
crates/​gateway/​stt/​api/​src/​lib.rs Exports speech paths and SpeechApi.
crates/​gateway/​stt/​api/​src/​batch.rs Documents multipart transcription and response schemas.
crates/​gateway/​stt/​api/​Cargo.toml Adds schema and error-envelope dependencies.
crates/​gateway/​README.md Links the generated API description.
crates/​gateway/​protocol/​src/​wire/​tests/​speech.rs Checks schema bounds against speech validation.
crates/​gateway/​protocol/​src/​wire/​speech.rs Derives speech schemas and declares bounds.
crates/​gateway/​protocol/​src/​wire/​rerank.rs Derives rerank schemas.
crates/​gateway/​protocol/​src/​wire/​envelope.rs Defines schema-only error-envelope types.
crates/​gateway/​protocol/​src/​wire/​embedding.rs Derives embedding schemas.
crates/​gateway/​protocol/​src/​wire.rs Derives chat schemas and exports error types.
crates/​gateway/​protocol/​Cargo.toml Adds utoipa.
crates/​gateway/​local/​src/​cache.rs Derives the cache-entry schema.
crates/​gateway/​local/​Cargo.toml Adds utoipa.
crates/​gateway/​config-ui/​src/​routes.rs Centralizes and exports asset paths.
crates/​gateway/​config-ui/​src/​lib.rs Re-exports asset paths for the registry.
crates/​gateway/​app/​tests/​fixtures/​oas-3.1/​schema-base-2026-08-03.json Supplies the offline schema-validation entry point.
crates/​gateway/​app/​tests/​fixtures/​oas-3.1/​schema-2026-08-03.json Vendors the OpenAPI document schema.
crates/​gateway/​app/​tests/​fixtures/​oas-3.1/​NOTICE Records vendored-schema attribution.
crates/​gateway/​app/​tests/​fixtures/​oas-3.1/​meta-2024-11-10.json Vendors OpenAPI vocabulary validation.
crates/​gateway/​app/​tests/​fixtures/​oas-3.1/​LICENSE Includes the vendored schemas’ license.
crates/​gateway/​app/​tests/​fixtures/​oas-3.1/​dialect-2024-11-10.json Vendors the OpenAPI schema dialect.
crates/​gateway/​app/​src/​web_search.rs Annotates the web-search operation.
crates/​gateway/​app/​src/​speech.rs Annotates speech routes and types the voices reply.
crates/​gateway/​app/​src/​speech-tests.rs Checks voices reply serialization equivalence.
crates/​gateway/​app/​src/​relay.rs Annotates chat, embeddings, and rerank operations.
crates/​gateway/​app/​src/​registry.rs Registers speech routes and config UI assets.
crates/​gateway/​app/​src/​registry-tests.rs Checks registered asset paths against exported paths.
crates/​gateway/​app/​src/​openapi/​markers.rs Adds extensions, error codes, and schema adjustments.
crates/​gateway/​app/​src/​openapi.rs Assembles feature-aware documents in tests.
crates/​gateway/​app/​src/​openapi-validity-tests.rs Checks offline validity, references, and overlapping unions.
crates/​gateway/​app/​src/​openapi-tests.rs Checks drift, coverage, features, and conventions.
crates/​gateway/​app/​src/​models.rs Documents the model catalog and its schemas.
crates/​gateway/​app/​src/​loopback-tests.rs Updates comments about asset-route coverage.
crates/​gateway/​app/​src/​lib.rs Wires in OpenAPI tests and updates registry comments.
crates/​gateway/​app/​src/​health.rs Documents health and introduces a typed reply.
crates/​gateway/​app/​src/​health-tests.rs Checks health reply serialization equivalence.
crates/​gateway/​app/​src/​cache.rs Documents cache operations and types the delete reply.
crates/​gateway/​app/​src/​cache-tests.rs Checks delete reply serialization equivalence.
crates/​gateway/​app/​src/​boot/​boot_speech_tests.rs Gates the realtime test helper on config-ui.
crates/​gateway/​app/​README.md Documents generation and verification commands.
crates/​gateway/​app/​Cargo.toml Adds utoipa and test-only JSON Schema validation.
crates/​gateway-api-types/​src/​metadata.rs Derives metadata schemas and marks extension fields.
crates/​gateway-api-types/​src/​lib.rs Updates dependency documentation.
crates/​gateway-api-types/​README.md Explains utoipa’s role in shared types.
crates/​gateway-api-types/​Cargo.toml Adds utoipa.
Cargo.toml Declares shared OpenAPI dependencies.
Cargo.lock Locks the added dependencies.
.github/​workflows/​ci.yml Checks OpenAPI generation without default features.

Review effort: Balanced

Comment on lines +191 to +194
("401", AUTH),
("404", &["model_not_found"]),
("429", &["queue_rejected"]),
("4XX", PASSED_THROUGH),

@awheeler294 awheeler294 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants