chore(deps): upgrade utoipa from 4.2.3 to 5.5.0#13314
Open
ayush22667 wants to merge 3 commits into
Open
Conversation
Bump utoipa (and utoipa-gen) across the workspace from 4.2.3 to 5.5.0. Source migration for the 4 -> 5 breaking changes: - Qualify all `#[schema(value_type = ...)]` references to full paths, since utoipa 5 no longer resolves bare type names against the local scope. - Add `#[schema(no_recursion)]` on the self-referential `IfStatement.nested` field (utoipa 5 added schema recursion detection). - Replace the removed `#[aliases(...)]` derive attribute with plain `pub type` aliases resolved by utoipa's native generics. - Add explicit `value_type` overrides for v2 newtypes that no longer derive `ToSchema` implicitly. utoipa 5 emits OpenAPI 3.1 (was 3.0). Regenerate both spec files and update the api-migrations-compatibility workflow to up-convert the base spec to 3.1 before diffing, bump oasdiff to v1.23.0, and record reviewed schema corrections in the new .oasdiff-* config files.
hyperswitch-bot
Bot
added
the
M-api-contract-changes
ayush22667
commented
Jul 15, 2026
Revert the api-migrations-compatibility scaffolding added for the utoipa 5 upgrade: restore oasdiff v1.11.7, drop the base-spec 3.1 up-conversion step and the --severity-levels / --err-ignore flags, and remove the accompanying config files. Restore the unreferenced .oasdiff-severity-levels.yaml this PR had deleted. The API & Migrations Compatibility check is expected to fail on this PR only: it compares the base branch's OpenAPI 3.0 spec against this PR's regenerated 3.1 spec. Once the 3.1 specs are on the base branch, subsequent PRs diff 3.1 vs 3.1 and the check passes without any workaround.
Contributor
Author
|
@copilot resolve the merge conflicts in this pull request ACCEPT THE UPCOMING CHANGES |
Contributor
There was a problem hiding this comment.
Pull request overview
Upgrades the workspace from utoipa 4.2.3 to 5.5.0 and performs the necessary annotation/macro migrations to keep OpenAPI generation working under utoipa 5 (OpenAPI 3.1) across router + openapi + shared model crates.
Changes:
- Bump
utoipa(and related usage) across multiple crates and updateCargo.lock. - Migrate
#[schema(...)]/#[utoipa::path(...)]usage to utoipa 5 expectations (notably fully-qualifiedvalue_typereferences and new schema overrides). - Introduce/adjust OpenAPI-only helper schemas (e.g., multipart file upload) and update route docs to reference
api_modelstypes explicitly.
Reviewed changes
Copilot reviewed 83 out of 87 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| crates/router/src/routes/poll.rs | Fully-qualify response body type in OpenAPI route annotation. |
| crates/router/src/routes/gsm.rs | Fully-qualify request/response body types in OpenAPI route annotations. |
| crates/router/src/routes/files.rs | Fully-qualify multipart request + response body types in OpenAPI route annotation. |
| crates/router/src/routes/disputes.rs | Update OpenAPI annotations to api_models::* types for disputes endpoints. |
| crates/router/src/routes/cards_info.rs | Fully-qualify response body type in OpenAPI route annotation. |
| crates/router/src/routes/blocklist.rs | Fully-qualify request/response/query types in OpenAPI route annotations. |
| crates/router/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/router_derive/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/openapi/src/routes/webhook_events.rs | Fully-qualify OpenAPI types referenced in route annotations. |
| crates/openapi/src/routes/tokenization.rs | Fully-qualify OpenAPI types referenced in route annotations. |
| crates/openapi/src/routes/three_ds_decision_rule.rs | Fully-qualify OpenAPI request/response types referenced in route annotation. |
| crates/openapi/src/routes/subscriptions.rs | Fully-qualify OpenAPI request/response/query types referenced in route annotations. |
| crates/openapi/src/routes/routing.rs | Fully-qualify OpenAPI request/response/query types referenced in route annotations. |
| crates/openapi/src/routes/revenue_recovery.rs | Fully-qualify OpenAPI response type referenced in route annotation. |
| crates/openapi/src/routes/relay.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/refunds.rs | Fully-qualify OpenAPI request/response/error types referenced in route annotations. |
| crates/openapi/src/routes/proxy.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/profile.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/profile_acquirer.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/poll.rs | Fully-qualify OpenAPI response type referenced in route annotation. |
| crates/openapi/src/routes/platform.rs | Fully-qualify OpenAPI request/response types referenced in route annotation. |
| crates/openapi/src/routes/payouts.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/payments.rs | Fully-qualify OpenAPI request/response/error types referenced in route annotations; add feature gating on some endpoints. |
| crates/openapi/src/routes/payment_method.rs | Fully-qualify OpenAPI request/response/query types referenced in route annotations; add feature gating on some endpoints. |
| crates/openapi/src/routes/payment_link.rs | Fully-qualify OpenAPI response type referenced in route annotation. |
| crates/openapi/src/routes/organization.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/merchant_connector_account.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/merchant_account.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/mandates.rs | Fully-qualify OpenAPI request/response/query types referenced in route annotations. |
| crates/openapi/src/routes/gsm.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/disputes.rs | Fully-qualify OpenAPI request/response/error types referenced in route annotations. |
| crates/openapi/src/routes/customers.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/card_issuer.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/src/routes/blocklist.rs | Fully-qualify OpenAPI request/response/query types referenced in route annotations. |
| crates/openapi/src/routes/authentication.rs | Fully-qualify OpenAPI request/response types referenced in route annotations; add feature gating on some endpoints. |
| crates/openapi/src/routes/api_keys.rs | Fully-qualify OpenAPI request/response types referenced in route annotations. |
| crates/openapi/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/hyperswitch_domain_models/src/router_request_types/fraud_check.rs | Add/adjust schema overrides for secret/newtype fields; derive ToSchema where needed. |
| crates/hyperswitch_domain_models/src/invoice.rs | Override schema for JSON metadata field for OpenAPI generation. |
| crates/hyperswitch_domain_models/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/hyperswitch_connectors/src/connectors/signifyd/transformers/api.rs | Remove utoipa::ToSchema usage/derives from connector-internal DTOs. |
| crates/hyperswitch_connectors/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/euclid/src/frontend/ast.rs | Add no_recursion, replace removed #[aliases] with type aliases, and qualify schema types for utoipa 5. |
| crates/euclid/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/connector_configs/src/common_config.rs | Add ToSchema derives and qualify value_type references for utoipa 5. |
| crates/connector_configs/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/common_utils/src/types.rs | Add schema override for URL newtype. |
| crates/common_utils/src/payout_method_utils.rs | Fully-qualify value_type references for enums in schema overrides. |
| crates/common_utils/src/link_utils.rs | Add schema overrides for secret/url fields and qualify enum schema types. |
| crates/common_utils/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/common_types/src/payments.rs | Qualify schema value_type references; adjust schema example placement; add ToSchema where needed. |
| crates/common_types/src/payment_methods.rs | Qualify schema value_type references for common enums. |
| crates/common_types/src/domain.rs | Qualify schema value_type references for enums. |
| crates/common_types/src/connector_webhook_configuration.rs | Qualify schema value_type references for event enums. |
| crates/common_types/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/common_enums/src/enums.rs | Add utoipa::ToSchema derive to selected enums for OpenAPI generation. |
| crates/common_enums/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| crates/api_models/src/webhooks.rs | Fully-qualify schema value_type references for content variants and enums. |
| crates/api_models/src/webhook_events.rs | Change schema representation for headers to avoid tuple schema issues under utoipa 5. |
| crates/api_models/src/user.rs | Qualify schema value_type references for common enums. |
| crates/api_models/src/unreferenced_refund.rs | Qualify schema value_type references; override schema for raw JSON connector response. |
| crates/api_models/src/three_ds_decision_rule.rs | Qualify schema value_type references for enums and decision type. |
| crates/api_models/src/routing.rs | Qualify schema value_type references for euclid AST aliases and open_router types. |
| crates/api_models/src/relay.rs | Qualify schema value_type references for enums and nested types. |
| crates/api_models/src/refunds.rs | Qualify schema value_type references; add missing value_type for ID newtype. |
| crates/api_models/src/profile_acquirer.rs | Qualify schema value_type references for country code enum. |
| crates/api_models/src/process_tracker/revenue_recovery.rs | Qualify schema value_type references; add value_type for ID newtype. |
| crates/api_models/src/payouts.rs | Qualify schema value_type references; normalize Currency usage. |
| crates/api_models/src/payments/additional_info.rs | Qualify schema value_type references for enums and nested payment types. |
| crates/api_models/src/oidc.rs | Add schema overrides for enum lists/newtypes to serialize as strings in OpenAPI. |
| crates/api_models/src/merchant_connector_webhook_management.rs | Fix schema value_type references for connector webhook enums. |
| crates/api_models/src/mandates.rs | Qualify schema value_type references for enums and nested types. |
| crates/api_models/src/gsm.rs | Qualify schema value_type references for enums and nested feature data. |
| crates/api_models/src/files.rs | Add OpenAPI helper type for multipart file upload schema. |
| crates/api_models/src/feature_matrix.rs | Qualify schema value_type references for common enums. |
| crates/api_models/src/errors/types.rs | Add ToSchema derive and schema override for arbitrary JSON data. |
| crates/api_models/src/customers.rs | Qualify schema value_type references; adjust schema for limit newtype. |
| crates/api_models/src/blocklist.rs | Qualify schema value_type references; add schema overrides for secret inputs. |
| crates/api_models/src/authentication.rs | Qualify schema value_type references for newtypes/enums and HTTP method. |
| crates/api_models/src/api_keys.rs | Migrate manual schema implementation to utoipa 5 (PartialSchema + ToSchema). |
| crates/api_models/Cargo.toml | Upgrade utoipa dependency to 5.5.0. |
| Cargo.lock | Lockfile updates for utoipa 5.5.0 and related transitive dependency changes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
167
to
171
| #[schema( | ||
| value_type = Vec<(String, String)>, | ||
| value_type = Vec<Vec<String>>, | ||
| example = json!([["content-type", "application/json"], ["content-length", "1024"]])) | ||
| ] | ||
| pub headers: Vec<(String, Secret<String>)>, |
Comment on lines
182
to
187
| /// The response headers received for the webhook sent. | ||
| #[schema( | ||
| value_type = Option<Vec<(String, String)>>, | ||
| value_type = Option<Vec<Vec<String>>>, | ||
| example = json!([["content-type", "application/json"], ["content-length", "1024"]])) | ||
| ] | ||
| pub headers: Option<Vec<(String, Secret<String>)>>, |
Comment on lines
489
to
493
| ("dispute_id" = String, Path, description = "The identifier for dispute") | ||
| ), | ||
| responses( | ||
| (status = 200, description = "The dispute evidence was retrieved successfully", body = DisputeResponse), | ||
| (status = 200, description = "The dispute evidence was retrieved successfully", body = api_models::disputes::DisputeResponse), | ||
| (status = 404, description = "Dispute does not exist in our records") |
Contributor
Done locally in commit |
…hemas
Address review feedback on the utoipa 5 upgrade:
- Revert the OutgoingWebhookRequestContent / OutgoingWebhookResponseContent
`headers` schema override from Vec<Vec<String>> back to the original
Vec<(String, String)>. The real field is Vec<(String, Secret<String>)>, so
the tuple form documents it as a fixed 2-element pair (OpenAPI prefixItems)
instead of an arbitrary-length string array.
- Fix the retrieve_dispute_evidence #[utoipa::path] response body on
GET /disputes/evidence/{dispute_id}: it returns Vec<DisputeEvidenceBlock>,
not DisputeResponse (the openapi-crate definition was already correct; this
aligns the router-crate annotation).
Regenerate the v1/v2 OpenAPI specs (webhook headers now render as prefixItems).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Type of Change
Description
Upgrades
utoipa(andutoipa-gen) from 4.2.3 to 5.5.0 across the Cargoworkspace. utoipa 5 emits OpenAPI 3.1 (previously 3.0) and ships several
breaking changes to the
#[derive(ToSchema)]/#[schema(...)]surface, so thisPR covers the source migration, the regenerated spec files, and the CI changes
needed to keep the API-compatibility check meaningful across the 3.0 -> 3.1
transition.
Source migration for the 4 -> 5 breaking changes:
#[schema(value_type = ...)]type references — utoipa 5 nolonger resolves bare type names (e.g.
Vec<BankNames>->Vec<api_enums::BankNames>).#[schema(no_recursion)]on the self-referentialeuclidIfStatement.nestedfield (utoipa 5 added schema recursion detection).
#[aliases(...)]derive attribute with plainpub typealiases resolved by utoipa's native generics (
euclid::frontend::ast).value_typeoverrides for v2 newtypes that no longer deriveToSchemaimplicitly.OpenAPI / CI:
api-reference/v1|v2/openapi_spec_*.json(now OpenAPI 3.1.0)..github/workflows/api-migrations-compatibility.ymlto up-convert thebase spec to 3.1 before diffing (so oasdiff compares 3.1-vs-3.1 rather than
flagging the whole re-encoding), bump oasdiff to v1.23.0, and record reviewed
schema corrections in the new
.oasdiff-severity-levels.txt/.oasdiff-err-ignore.txtconfig, with a README documenting the transition.Additional Changes
The change is to the OpenAPI spec representation (3.0 -> 3.1 encoding, plus a
few schemas corrected to match the actual Rust types — e.g.
number_of_installments,optional
feature_data); no runtime request/response behavior changes.See
api-reference/v1/openapi_spec_v1.json,api-reference/v2/openapi_spec_v2.json,and
.github/api-migration-compatibility/.oasdiff-err-ignore.txt.Motivation and Context
Keeps the OpenAPI tooling current, unblocks features that depend on utoipa 5
(OpenAPI 3.1, native generic schemas, recursion detection), and moves off the
unmaintained 4.x line.
Linked Issues
How did you test it?
just check(v1) andjust check_v2(v2) — both compile clean.just clippy(v1) andjust clippy_v2(v2) — both pass with-D warnings.cargo run -p openapi --features v1and--features v2and confirmed the committed files match the generator output(the
validate-openapi-specCI gate); generation is deterministic.Checklist
cargo +nightly fmt --allcargo clippy