Skip to content

Conversation

@kieled
Copy link

@kieled kieled commented Feb 7, 2026

Fixes #255.
Fixes #272.
Fixes #235.

This PR addresses two high-impact adoption pain points:

  1. Docs/onboarding: doctest examples failed to compile
  • The docs examples called axum::serve(...) which is feature-gated in axum (tokio + http1/http2). With axum used with default-features = false, axum::serve is not always available, causing doctest failures.
  • The main aide::axum example also unnecessarily forced the /api.json route through IntoApiResponse even though it is not documented (added via .route, not .api_route).

Changes:

  • Update doc examples in:
    • crates/aide/src/axum/mod.rs
    • crates/aide/src/redoc/mod.rs
    • crates/aide/src/swagger/mod.rs
    • crates/aide/src/scalar/mod.rs
      to avoid calling axum::serve in doctests.
  • Use plain axum routing::get + IntoResponse for the non-documented /api.json handler in the aide::axum docs example.
  1. OperationInput inference: early responses
  • OperationIo with input_with = ... previously delegated operation_input but did not delegate OperationInput::inferred_early_responses, so early responses were silently dropped.
  • axum::Json<T> did not provide inferred early responses, even though axum returns rejections before the handler body for invalid JSON and content-type mismatches.

Changes:

  • OperationIo now forwards inferred_early_responses when input_with is used.
  • axum::Json<T> now reports inferred early responses:
    • 400: failed to parse JSON
    • 415: missing/invalid Content-Type: application/json
    • 422: valid JSON but failed to deserialize into the target type

Tests:

  • Added/extended tests covering:
    • OperationIo forwarding of inferred_early_responses
    • axum::Json<T> inferred early response status codes

Commands run:

  • cargo test -p aide --doc --all-features
  • cargo test --workspace --all-features
  • cargo build --examples --all-features

(These changes should also reduce confusion seen in #278 and #265 by removing common docs-triggered failure modes.)

@jplatte
Copy link
Collaborator

jplatte commented Feb 7, 2026

Please split into at least two PRs (docs, inferred_early_responses).

@kieled
Copy link
Author

kieled commented Feb 7, 2026

Split per review request:

This PR is superseded by those two.

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

Labels

None yet

Projects

None yet

2 participants