asmhatreandClaude Sonnet 5
8d0efb0d4b
Companion module for "springdoc-openapi with Spring Boot 4.1: Generating, Customising and Versioning Your API Spec". Reuses the ApiVersionConfigurer setup from the versioning-mechanics companion project and tests what springdoc-openapi 3.1.1 actually generates for a path with multiple version-scoped handlers: a default oneOf-merged operation with an arbitrary operationId, a working GroupedOpenApi + OpenApiCustomizer fix that collapses it to one clean schema per version, and a check of the officially-versioning-supported functional-endpoint path (springdoc v3.0.2's "Add support for Spring Framework API Versioning with Functional Endpoints"), which turns out to document only one of two registered versions rather than either version separately. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01M1uZDXWkY1MnTfQgt4HMeQ
3.1 KiB
Known issues, checked directly rather than assumed
Three springdoc-openapi GitHub issues are relevant enough to this module's topic to be worth listing — checked directly against the live issue tracker rather than repeated from memory, and reported here with exactly the confidence the check supports, not more.
#2975 — "Spring Framework 7 - API versioning support"
Opened 28 April 2025, requesting that springdoc generate separate OpenAPI specs per API version
once Framework 7 shipped its versioning support. Status: closed, as of this module's research
(September 2026). I could not retrieve a linked resolving PR or a maintainer closing comment
through the tools available to this project — so treat "closed" as confirmed and the reason it
was closed as unconfirmed. What this module confirms independently, by actually running the code,
is the substantive question the issue asked about: springdoc 3.1.1 does not generate separate
specs per version on its own (see chapter 2); the
GroupedOpenApi approach in chapter 5 is a workaround you build
yourself, not built-in behaviour that shipped in response to this issue.
#3354 — "OpenAPI generation fails when MVC API version default is absent from @Schema allowableValues"
Open as of September 2026, reported against springdoc-openapi 3.0.3 and confirmed by its author
still present in 3.1.0, 3.1.1, and the main branch. Described root cause: AbstractRequestService.getHeaders()
attempts to add the configured default API version into an operation's @Schema(allowableValues = ...) enum when that operation doesn't already support the default version, and that enum can be
an immutable list, producing UnsupportedOperationException → HTTP 500 from /v3/api-docs.
I did not reproduce this specific crash in this module. I tried the closest natural trigger —
setDefaultVersion("1") combined with both an explicit addSupportedVersions(...) list and
detectSupportedVersions(true) — and in both cases /v3/api-docs returned a normal 200 (see
chapter 2's transcript). The issue's description points
at an operation carrying its own explicit @Schema(allowableValues = ...) that doesn't include the
default version, which is a narrower and more specific setup than anything in this module's
AccountController. I'm listing it here as a real, open, citable issue worth knowing about if
you're debugging a 500 from your own /v3/api-docs with versioning enabled — not as something
this module demonstrates first-hand.
#3163 — "HTTP 400 with Spring Boot 4 API versioning enabled"
Closed and labelled invalid — the reporter saw /swagger-ui.html and /v3/api-docs return 400
with API versioning properties set via spring.mvc.apiversion.*. Listed here mainly so it doesn't
get confused with #3354 above: this one was determined by maintainers not to be a genuine
springdoc bug (most likely a request routing/configuration issue on the reporter's side, based on
the invalid label), separate from the still-open schema-enum crash in #3354.