Add openapi-versioning: springdoc-openapi 3.1.1 vs Spring Framework 7 API versioning

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
2026-09-17 19:31:42 +00:00
parent a875bea55a
commit 8d0efb0d4b
26 changed files with 1163 additions and 0 deletions
@@ -0,0 +1,43 @@
+# 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](02-what-springdoc-actually-generates.md)); the
+`GroupedOpenApi` approach in [chapter 5](05-the-grouped-openapi-fix.md) 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](02-what-springdoc-actually-generates.md)'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.