OpenAPI Architecture

How the relayer's OpenAPI spec is generated, what design decisions shape it, and how to maintain it.

1. Generation pipeline

Rust types (#[derive(ToSchema)])  ──┐
                                    ├──► ApiDoc (#[derive(OpenApi)])
Handler annotations (#[utoipa::path]) ┘            │
                                                   ▼
                                       build_openapi_doc()
                                          │
                           ┌──────────────┼──────────────┐
                           ▼              ▼              ▼
                   TagGroupModifier  ErrorLabelEnricher  ExampleInjector
                           │              │              │
                           ▼              ▼              ▼
                       utoipa::openapi::OpenApi (in-memory)
                                          │
                                          ▼
                               serde_yaml::to_string()
                                          │
                                          ▼
                   Post-processing (hex quoting only — no YAML AST manipulation)
                                          │
                                          ▼
                                  openapi.yml

1.1 Schema generation

• 43 #[derive(ToSchema)] across 8 files produce JSON Schema components
• Key #[schema(...)] attrs used:
  • example — field-level inline examples
  • value_type — override inferred type (e.g. pin V2ErrorLabel on a String field)
  • min_items — array constraints (e.g. ciphertextHandles)
• serde attrs propagate automatically:
  • rename_all = "camelCase" → property names
  • skip_serializing_if = "Option::is_none" → nullable, not required
  • untagged → oneOf without discriminator
• Doc comments (///) become description fields in the spec

1.2 Path/operation generation

• 12 #[utoipa::path] annotations across 5 handler files
• Each annotation specifies: HTTP method, path, request body, responses(...) with status codes + body types, tag
• Error examples are auto-generated by ExampleInjector from ERROR_MATRIX (no hand-maintained examples(...) blocks)
• Thin wrapper functions exist solely for utoipa — real logic lives on impl handler blocks:

#[utoipa::path(post, path = "/v2/input-proof", ...)]
pub async fn input_proof_post_v2<D>(handler: Arc<InputProofHandler<D>>, req: Request<...>) -> impl IntoResponse {
    handler.input_proof_post_v2(req).await
}

1.3 Assembly

ApiDoc in src/http/middleware/openapi.rs:

• #[derive(OpenApi)] macro wires everything together
• paths(...) — 12 handler functions (9 v2 + 3 health)
• components(schemas(...)) — all request/response/error types
• tags(...) — 6 tags (5 endpoint groups + Health)
• modifiers(&TagGroupModifier, &ErrorLabelEnricher, &ExampleInjector) — three Modify trait impls (see §1.4)
• build_openapi_doc() → returns utoipa::openapi::OpenApi
• openapi_middleware() → serves Redoc UI at /docs

1.4 Modifiers (utoipa Modify trait)

All three modifiers operate on the in-memory OpenApi struct before serialization — no YAML string manipulation.

ErrorLabelEnricher detail

Two-phase modify():

1. Error reference table — iterates ERROR_LABEL_DEFS, builds a markdown table with columns Label | HTTP | SDK Action, replaces the <!-- ERROR_LABEL_TABLE --> placeholder in info.description
2. Per-response label summaries — walks openapi.paths.paths, filters to /v2/ endpoints, calls labels_for_status(path, status, is_post) for each error status code, appends a backtick-formatted label list to the response description

ExampleInjector detail

Walks openapi.paths.paths, filters to /v2/ endpoints, and for each error status code:

• Calls labels_for_status(path, status, is_post) to get the labels
• Builds a JSON envelope per label with status, error.label, error.message
• Adds requestId for all errors except POST 429 rate_limited
• Adds details[] for validation_failed and missing_fields labels
• Inserts into content.examples as BTreeMap<PascalCaseLabel, Example>

Data sources:

1.5 Post-processing

src/bin/openapi-export.rs applies one transform after serde_yaml::to_string():

1.6 CI and runtime

2. Type architecture

Two-layer type system

OpenAPI-only types are documentation artifacts — they don't need Deserialize, constructors, or methods.

Error hierarchy

V2ApiError {label, message}
V2ApiErrorWithDetails {label, message, details[]}
        │
        ▼
V2ErrorResponseBody (untagged oneOf)
        │
        ├──► RelayerV2ResponseFailed  (POST 4xx/5xx wrapper)
        └──► V2StatusFailed           (GET 4xx/5xx wrapper)

• V2ErrorLabel enum — 16 variants, rendered as enum in spec
• all_error_labels() function — derived from ERROR_LABEL_DEFS, no manual maintenance needed
• Drift tests (see §3) ensure labels, metadata, and spec examples stay in sync

Known duplication

Three endpoint groups repeat identical shapes:

3. Drift detection

Five tests across two modules form a closed verification loop:

Together these ensure: add a label to ERROR_LABEL_DEFS → must add catalog entry → examples auto-generated. Missing any step fails CI.

4. Pros and cons

What works well

• Single source of truth — spec derived from code, CI prevents drift
• Per-status-code schemas — consumers know exact shape per HTTP status
• Typed error bodies with label enum — machine-readable, no opaque serde_json::Value
• Closed drift-test loop — catches label, metadata, and example drift at build time
• Modify trait modifiers — operate on typed OpenApi struct, not fragile YAML strings
• x-tagGroups — organizes Redoc sidebar into Endpoints vs Operations

What is fragile

• labels_for_status() is a manual mapping that must stay in sync with handler code. Drift tests check labels exist, but not that the mapping matches actual handler error paths.
• Two type layers means field changes touch both runtime and OpenAPI-only types.

utoipa limitations

5. Maintenance playbook

Adding a new V2 endpoint

1. Create request/response types with #[derive(ToSchema)]
2. Create *SucceededStatusResponse (OpenAPI-only) and *StatusResponseJson (runtime)
3. Add thin wrapper function with #[utoipa::path] annotation (error examples are auto-generated)
4. Register path + schemas in ApiDoc (openapi.rs)
5. Add endpoint to labels_for_status() in expected_labels.rs
6. make openapi-generate + commit openapi.yml

Adding a new error label

1. Add entry to ERROR_LABEL_DEFS in expected_labels.rs (all_error_labels() is derived automatically)
2. Add variant to V2ErrorLabel enum in error.rs
3. Add constructor method on V2ErrorResponseBody (enforced by all_constructor_labels_are_in_canonical_list test)
4. Add to ERROR_MATRIX in expected_labels.rs (examples are auto-generated by ExampleInjector)
5. make openapi-generate

Modifying response fields

1. Update both the runtime type (*StatusResponseJson) and OpenAPI-only type (*SucceededStatusResponse)
2. make openapi-generate (error examples are auto-regenerated)

6. Cross-references