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
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,38 @@
|
||||
# Versions and setup
|
||||
|
||||
| Component | Version | Source of truth |
|
||||
|---|---|---|
|
||||
| Spring Boot | 4.1.1 | `pom.xml` parent |
|
||||
| Spring Framework | 7.0.9 | resolved transitively by the Boot 4.1.1 BOM |
|
||||
| springdoc-openapi | 3.1.1 | `pom.xml` property `springdoc.version`; confirmed as the current `<latest>`/`<release>` against Maven Central's `springdoc-openapi-starter-webmvc-ui/maven-metadata.xml` (`lastUpdated` 2026-09-06T16:37:40Z) |
|
||||
| JDK | 25 (Temurin 25.0.4.1+1) | `java -version` on the build host |
|
||||
|
||||
Single dependency beyond the web starter:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
|
||||
<version>3.1.1</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
No other springdoc configuration is required to get `/v3/api-docs` and `/swagger-ui.html` — both
|
||||
are enabled by default (springdoc logs a `WARN` about this at startup, pointing at
|
||||
`springdoc.api-docs.enabled=false` / `springdoc.swagger-ui.enabled=false` for production).
|
||||
|
||||
## The versioning setup this module builds on
|
||||
|
||||
[`WebConfig`](../src/main/java/com/ankurm/openapiversioning/config/WebConfig.java) is the *exact*
|
||||
`ApiVersionConfigurer` setup from the companion project for [Spring Framework 7 API
|
||||
Versioning: The Complete Guide](https://ankurm.com/spring-framework-7-api-versioning-guide/):
|
||||
header-based resolution (`API-Version`), `setVersionRequired(false)`, `setDefaultVersion("1")`.
|
||||
That article already verified the versioning *mechanics* — baseline handlers, the
|
||||
supported-versions allow-list, what an unversioned request resolves to. This module deliberately
|
||||
does not re-litigate any of that; it takes the mechanics as given and asks a narrower question:
|
||||
once you add springdoc-openapi on top, what actually ends up in the generated spec?
|
||||
|
||||
[`AccountController`](../src/main/java/com/ankurm/openapiversioning/web/AccountController.java)
|
||||
mirrors that article's three-handler shape (`version = "1"`, `"1.1+"`, `"2"`), with one addition:
|
||||
an `AccountStatus` enum on the v2 response, so the OpenAPI output actually exercises enum
|
||||
handling, not just flat string fields.
|
||||
@@ -0,0 +1,74 @@
|
||||
# What springdoc actually generates for a versioned path
|
||||
|
||||
Full transcript: [docs/output/02-what-springdoc-actually-generates.txt](output/02-what-springdoc-actually-generates.txt),
|
||||
produced by `OpenApiVersioningTest#b_defaultApiDocsMergesAllVersionsIntoOneOf`.
|
||||
|
||||
Hit the plain, ungrouped `/v3/api-docs` on this module — no custom configuration beyond adding
|
||||
the starter — and here is the entire operation springdoc built for `GET /accounts/{id}`, which
|
||||
has three handlers mapped to it (`version = "1"`, `"1.1+"`, `"2"`):
|
||||
|
||||
```json
|
||||
{
|
||||
"operationId": "getAccountV2",
|
||||
"parameters": [
|
||||
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
|
||||
{
|
||||
"name": "API-Version",
|
||||
"in": "header",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"default": "1.0.0",
|
||||
"enum": ["2", "1", "1.0.0", "1.1"]
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"content": {
|
||||
"*/*": {
|
||||
"schema": {
|
||||
"oneOf": [
|
||||
{ "$ref": "#/components/schemas/AccountV1" },
|
||||
{ "$ref": "#/components/schemas/AccountV2" },
|
||||
{ "$ref": "#/components/schemas/AccountV1Point1" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Three things worth naming precisely, since none of them are documented behaviour as far as I
|
||||
could find — this is what running it produced, not what any springdoc doc page promises:
|
||||
|
||||
**One operation, not three.** springdoc does not know that `version` is a routing discriminant
|
||||
the way it knows `@PathVariable` or `@RequestParam` are. As far as its operation-building code is
|
||||
concerned, three `HandlerMethod`s map to the same path and HTTP method, so it folds them into one
|
||||
`Operation` — the same folding it would do for, say, an overloaded controller method disambiguated
|
||||
by a `headers = "X-Foo"` condition.
|
||||
|
||||
**The response schema becomes `oneOf` all three shapes, with no discriminator.** This is
|
||||
technically *not wrong* — a client that doesn't send `API-Version` really could get any of the
|
||||
three shapes back, so `oneOf` is a defensible schema for "the operation's response, considered
|
||||
without reference to versioning." But it is unusable as version-specific documentation: nothing in
|
||||
this schema says which shape maps to which version.
|
||||
|
||||
**`operationId` is picked from whichever handler springdoc processes last, arbitrarily from the
|
||||
reader's perspective.** It happened to be `getAccountV2` here. Generated API clients
|
||||
(openapi-generator, openapi-typescript, etc.) use `operationId` as the method name they generate —
|
||||
so a client generated from this spec gets one method, named after one version, that claims to
|
||||
return `oneOf` three different shapes.
|
||||
|
||||
**The auto-documented `API-Version` header enum is also slightly wrong on its own terms**: it
|
||||
lists `"1"` and `"1.0.0"` as if they were two different values, when `"1.0.0"` is just the
|
||||
semantic-version-normalised form of the same default `"1"` configured in `WebConfig`
|
||||
(`setDefaultVersion("1")`). Framework 7's version parser is doing exactly what it's supposed to —
|
||||
`1` and `1.0.0` really do compare equal — but springdoc surfaces both the raw configured string and
|
||||
the normalised form as if a caller could sensibly choose between them.
|
||||
|
||||
None of this is a crash — the document is valid OpenAPI 3.1, it just isn't the document most teams
|
||||
actually want from a versioned API. [The next chapter](05-the-grouped-openapi-fix.md) is a working
|
||||
fix for the first two problems; the header-enum oddity is cosmetic enough that I didn't chase it
|
||||
further, and is called out in [06-known-issues.md](06-known-issues.md) instead.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Why the version→schema map in the fix is hand-maintained
|
||||
|
||||
[`VersionedOpenApiConfig`](../src/main/java/com/ankurm/openapiversioning/config/VersionedOpenApiConfig.java)
|
||||
keeps a small, explicit `Map<String, VersionSpec>` from version string to schema name /
|
||||
operationId / summary, rather than deriving that mapping automatically from the running
|
||||
application. This is a deliberate limitation, not an oversight, and it's worth being honest about
|
||||
why: an `OpenApiCustomizer` (`org.springdoc.core.customizers.OpenApiCustomizer`) receives exactly
|
||||
one argument, the fully-built `io.swagger.v3.oas.models.OpenAPI` document — see
|
||||
`javap org/springdoc/core/customizers/OpenApiCustomizer.class`:
|
||||
|
||||
```
|
||||
public interface org.springdoc.core.customizers.OpenApiCustomizer {
|
||||
public abstract void customise(io.swagger.v3.oas.models.OpenAPI);
|
||||
}
|
||||
```
|
||||
|
||||
By the time a customizer runs, springdoc has already folded the three `HandlerMethod`s into one
|
||||
merged `Operation` (see the previous chapter) — the association between "this specific handler
|
||||
method" and "this specific version string" has already been discarded. An `OperationCustomizer`
|
||||
(`org.springdoc.core.customizers.OperationCustomizer`) does get a `HandlerMethod` argument per
|
||||
call, which looks more promising, but it still runs once per merged operation, not once per
|
||||
original handler — it cannot see the three original mappings separately either, because springdoc
|
||||
folds first and customizes second. There is no supported extension point in 3.1.1 that intercepts
|
||||
before the fold.
|
||||
|
||||
Reflectively pulling the `version` condition back out of Spring's own `RequestMappingInfo` (via
|
||||
`RequestMappingHandlerMapping.getHandlerMethods()`) would work at the Spring MVC layer — Framework
|
||||
7 exposes it there in principle — but wiring that into springdoc's generation pipeline means
|
||||
matching springdoc's internal notion of "this operation" back to Spring's `RequestMappingInfo` by
|
||||
path and method, which is exactly the kind of implementation-detail-coupled reflection that breaks
|
||||
silently on the next springdoc minor version. A hand-maintained map keyed by the version strings
|
||||
you already wrote in your own `@GetMapping(version = ...)` annotations is three lines of
|
||||
boilerplate per version and it does not break when springdoc changes how it folds operations
|
||||
internally.
|
||||
@@ -0,0 +1,99 @@
|
||||
# The functional-endpoint path: officially supported, and worse
|
||||
|
||||
springdoc-openapi's [v3.0.2 release notes](https://github.com/springdoc/springdoc-openapi/releases/tag/v3.0.2)
|
||||
(28 Feb 2026) list, under **Added**: "#3229 – Add support for Spring Framework API Versioning with
|
||||
Functional Endpoints." Reading that changelog line on its own, it's reasonable to expect functional
|
||||
(`RouterFunction`) endpoints to be the *better*-supported path for versioned APIs in springdoc —
|
||||
official, named support, versus the annotated-controller behaviour in the previous chapter that
|
||||
nothing documents. I built [`WidgetRouterConfig`](../src/main/java/com/ankurm/openapiversioning/functional/WidgetRouterConfig.java)
|
||||
to check.
|
||||
|
||||
Full transcript: [docs/output/06-functional-endpoint-path.txt](output/06-functional-endpoint-path.txt),
|
||||
from `OpenApiVersioningTest#d_functionalEndpointVersioningRuntimeWorksButDocsDoNot`.
|
||||
|
||||
## The setup
|
||||
|
||||
Two handler methods, one `RouterFunction` with Framework 7's `RequestPredicates.version(...)`
|
||||
doing the routing, and springdoc's `@RouterOperations`/`@RouterOperation` — the mechanism
|
||||
functional endpoints have always needed for OpenAPI documentation, since there's no
|
||||
`@GetMapping` for springdoc to reflect on:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
@RouterOperations({
|
||||
@RouterOperation(path = "/widgets/{id}", method = GET, beanClass = WidgetHandler.class, beanMethod = "getWidgetV1"),
|
||||
@RouterOperation(path = "/widgets/{id}", method = GET, beanClass = WidgetHandler.class, beanMethod = "getWidgetV2")
|
||||
})
|
||||
public RouterFunction<ServerResponse> widgetRoutes(WidgetHandler handler) {
|
||||
return RouterFunctions.route()
|
||||
.GET("/widgets/{id}", RequestPredicates.version("1"), handler::getWidgetV1)
|
||||
.GET("/widgets/{id}", RequestPredicates.version("2"), handler::getWidgetV2)
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
First thing worth checking before running anything: `@RouterOperation` itself has **no version
|
||||
attribute** (`javap org/springdoc/core/annotations/RouterOperation.class` — `path`, `method`,
|
||||
`consumes`, `produces`, `headers`, `params`, `beanClass`, `beanMethod`, `parameterTypes`,
|
||||
`operation`; nothing else). Whatever PR #3229 added, it did not add a way to tell springdoc which
|
||||
version a given `@RouterOperation` documents.
|
||||
|
||||
## Runtime: correct
|
||||
|
||||
```
|
||||
GET /widgets/7, API-Version: 1 -> {"id":"7","apiVersion":"1"}
|
||||
GET /widgets/7, API-Version: 2 -> {"widgetId":"7","apiVersion":"2"}
|
||||
```
|
||||
|
||||
Framework 7's `version(...)` `RequestPredicate` routes correctly — no surprise there, that's
|
||||
Framework's job, not springdoc's, and it was already verified independently in the companion
|
||||
project for the versioning-mechanics article.
|
||||
|
||||
## Documentation: worse than the annotated-controller case
|
||||
|
||||
```json
|
||||
{
|
||||
"tags": ["widget-handler"],
|
||||
"operationId": "getWidgetV1",
|
||||
"responses": {
|
||||
"200": {
|
||||
"content": { "*/*": { "schema": { "$ref": "#/components/schemas/ServerResponse" } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Two registered `@RouterOperation`s went in; **one operation came out**, silently — not merged into
|
||||
a `oneOf` the way the annotated `@GetMapping` handlers were in the previous chapter, just dropped.
|
||||
In this build it was consistently the first-declared entry (`getWidgetV1`) that survived across
|
||||
repeated `mvn test` runs; I did not chase the exact selection rule (declaration order in the
|
||||
`@RouterOperations` array vs. `RouterFunction` registration order) because it doesn't change the
|
||||
practical takeaway — springdoc does not attempt to represent both versions of a functional
|
||||
endpoint at all, which is a strictly worse outcome for a reader than the annotated-controller
|
||||
`oneOf` merge, not a fix for it.
|
||||
|
||||
The response schema resolving to a near-empty `ServerResponse` component (rather than either
|
||||
handler's actual JSON shape) is a separate, pre-existing springdoc limitation of functional
|
||||
endpoints in general: `@RouterOperation.operation()` lets you attach a full `@Operation`
|
||||
annotation with an explicit response type, and without it springdoc falls back to introspecting
|
||||
the handler method's own return type — which for a functional endpoint is always `ServerResponse`,
|
||||
not whatever body you happen to construct inside it. That fallback isn't about versioning at all;
|
||||
it would happen on an unversioned functional endpoint too.
|
||||
|
||||
**My best reading of what #3229 actually fixed**, based on this and on the same release's fix
|
||||
entry "#3232 – Gracefully handle springdoc endpoint paths during API version resolution": Spring's
|
||||
own request-mapping introspection previously had no case for a `version(...)` predicate node in a
|
||||
functional route's predicate tree, which made springdoc's *own* endpoints (`/v3/api-docs`,
|
||||
`/swagger-ui.html`, etc.) trip over API version resolution once versioning was enabled at all,
|
||||
functional endpoints or not. #3229 most plausibly taught springdoc's router-visiting code to walk
|
||||
past a `version(...)` predicate node without erroring — not to generate a separate operation per
|
||||
version. I can't fully confirm that reading from the outside (the PR's own diff isn't part of the
|
||||
release notes text), so treat it as my best inference from the observed behaviour rather than a
|
||||
confirmed fact — but the observed behaviour itself (one operation survives, not versioned
|
||||
separately) is directly reproduced above and is not in question.
|
||||
|
||||
**Practical takeaway: if you need real per-version OpenAPI documentation today, the annotated
|
||||
`@GetMapping` + `GroupedOpenApi` customizer approach in the next chapter is the one that actually
|
||||
works.** The functional-endpoint path is not currently a better-documented alternative for
|
||||
versioned APIs, whatever "Add support for ... Functional Endpoints" in the changelog might suggest
|
||||
on its own.
|
||||
@@ -0,0 +1,60 @@
|
||||
# The fix: one GroupedOpenApi per version
|
||||
|
||||
Full transcript: [docs/output/05-grouped-openapi-fix.txt](output/05-grouped-openapi-fix.txt), from
|
||||
`OpenApiVersioningTest#c_groupedOpenApiCustomizerCollapsesToOneCleanSchemaPerVersion`.
|
||||
|
||||
[`VersionedOpenApiConfig`](../src/main/java/com/ankurm/openapiversioning/config/VersionedOpenApiConfig.java)
|
||||
registers three `GroupedOpenApi` beans — one per supported version — each scoped to
|
||||
`/accounts/**` and each carrying an `OpenApiCustomizer` that collapses the merged `oneOf` response
|
||||
from the previous chapter down to the one schema that version's clients actually receive, fixes
|
||||
`operationId` and `summary` to match, and drops the now-meaningless `API-Version` header:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
public GroupedOpenApi accountsV1Group() {
|
||||
return groupFor("accounts-v1", "1");
|
||||
}
|
||||
|
||||
private GroupedOpenApi groupFor(String groupName, String version) {
|
||||
VersionSpec spec = SPECS.get(version);
|
||||
return GroupedOpenApi.builder()
|
||||
.group(groupName)
|
||||
.pathsToMatch("/accounts/**")
|
||||
.addOpenApiCustomizer(collapseToSingleVersion(spec))
|
||||
.build();
|
||||
}
|
||||
```
|
||||
|
||||
Each group is served at `/v3/api-docs/{group}` (springdoc's own convention — no extra wiring
|
||||
needed). Result, all three fetched from the same running instance:
|
||||
|
||||
```
|
||||
GET /v3/api-docs/accounts-v1 -> operationId=getAccountV1, schema=AccountV1, params=[id]
|
||||
GET /v3/api-docs/accounts-v1.1 -> operationId=getAccountV1Point1Plus, schema=AccountV1Point1, params=[id]
|
||||
GET /v3/api-docs/accounts-v2 -> operationId=getAccountV2, schema=AccountV2, params=[id]
|
||||
```
|
||||
|
||||
Each is a clean, single-schema operation — feed any one of these three documents into
|
||||
openapi-generator and you get one method whose declared response type is actually what that
|
||||
version's clients receive, not a `oneOf` of three.
|
||||
|
||||
**The default, ungrouped `/v3/api-docs` is untouched** — confirmed by re-fetching it inside the
|
||||
same test, immediately after fetching all three groups, and it still shows the exact `oneOf` merge
|
||||
from the previous chapter. `GroupedOpenApi`'s customizer runs against a document scoped to that
|
||||
group's own build, not the shared default document, so adding version-specific groups is additive:
|
||||
existing tooling pointed at the plain `/v3/api-docs` (or Swagger UI's default view) keeps working
|
||||
exactly as it did before, while `/v3/api-docs/accounts-v2` becomes a new, additional,
|
||||
clean-per-version resource for anyone who wants one — a generated TypeScript client for your v2
|
||||
mobile app, say, without also generating types for the v1 shape it will never receive.
|
||||
|
||||
See [the previous chapter](03-why-a-hand-maintained-map.md) for why the version→schema mapping
|
||||
this customizer applies is a small hand-written `Map`, not something derived automatically from
|
||||
the running handler mappings — that's a real limitation of the public springdoc customizer API,
|
||||
not a shortcut taken for the sake of the demo.
|
||||
|
||||
## Swagger UI
|
||||
|
||||
With three additional groups registered, `/swagger-ui.html` grows a group selector (`default`,
|
||||
`accounts-v1`, `accounts-v1.1`, `accounts-v2`) — switching between them re-fetches the
|
||||
corresponding `/v3/api-docs/{group}` document, so the same collapsed, single-schema view is what a
|
||||
human reading the UI sees too, not just API clients hitting the JSON directly.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,2 @@
|
||||
Spring Boot 4.1.1 / Spring Framework 7.0.9 / springdoc-openapi 3.1.1 / JDK 25 (Temurin 25.0.4.1+1)
|
||||
springdoc-openapi-starter-webmvc-ui:3.1.1, resolved from Maven Central maven-metadata.xml (latest=release=3.1.1, lastUpdated 2026-09-06T16:37:40Z).
|
||||
@@ -0,0 +1,11 @@
|
||||
GET /accounts/42, API-Version: 1
|
||||
200
|
||||
{"id":"42","name":"Ankur Mhatre","apiVersion":"1"}
|
||||
|
||||
GET /accounts/42, API-Version: 1.1
|
||||
200
|
||||
{"id":"42","name":"Ankur Mhatre","email":"[email protected]","apiVersion":"1.1+"}
|
||||
|
||||
GET /accounts/42, API-Version: 2
|
||||
200
|
||||
{"accountId":"42","displayName":"Ankur Mhatre","contact":{"email":"[email protected]"},"status":"ACTIVE","apiVersion":"2"}
|
||||
@@ -0,0 +1,160 @@
|
||||
GET /v3/api-docs (ungrouped, default), operation at /accounts/{id}:
|
||||
operationId = getAccountV2 (picked from ONE of the three handlers, not versioned itself)
|
||||
response schema = oneOf [3 entries]: #/components/schemas/AccountV1, #/components/schemas/AccountV2, #/components/schemas/AccountV1Point1
|
||||
API-Version header enum (auto-documented) = ["2","1","1.0.0","1.1"]
|
||||
API-Version header default = "1.0.0"
|
||||
|
||||
Full raw document:
|
||||
{
|
||||
"openapi" : "3.1.0",
|
||||
"info" : {
|
||||
"title" : "OpenAPI definition",
|
||||
"version" : "v0"
|
||||
},
|
||||
"servers" : [ {
|
||||
"url" : "http://localhost:36991",
|
||||
"description" : "Generated server url"
|
||||
} ],
|
||||
"paths" : {
|
||||
"/accounts/{id}" : {
|
||||
"get" : {
|
||||
"tags" : [ "account-controller" ],
|
||||
"operationId" : "getAccountV2",
|
||||
"parameters" : [ {
|
||||
"name" : "id",
|
||||
"in" : "path",
|
||||
"required" : true,
|
||||
"schema" : {
|
||||
"type" : "string"
|
||||
}
|
||||
}, {
|
||||
"name" : "API-Version",
|
||||
"in" : "header",
|
||||
"schema" : {
|
||||
"type" : "string",
|
||||
"default" : "1.0.0",
|
||||
"enum" : [ "2", "1", "1.0.0", "1.1" ]
|
||||
}
|
||||
} ],
|
||||
"responses" : {
|
||||
"200" : {
|
||||
"description" : "OK",
|
||||
"content" : {
|
||||
"*/*" : {
|
||||
"schema" : {
|
||||
"oneOf" : [ {
|
||||
"$ref" : "#/components/schemas/AccountV1"
|
||||
}, {
|
||||
"$ref" : "#/components/schemas/AccountV2"
|
||||
}, {
|
||||
"$ref" : "#/components/schemas/AccountV1Point1"
|
||||
} ]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/widgets/{id}" : {
|
||||
"get" : {
|
||||
"tags" : [ "widget-handler" ],
|
||||
"operationId" : "getWidgetV1",
|
||||
"responses" : {
|
||||
"200" : {
|
||||
"description" : "OK",
|
||||
"content" : {
|
||||
"*/*" : {
|
||||
"schema" : {
|
||||
"$ref" : "#/components/schemas/ServerResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components" : {
|
||||
"schemas" : {
|
||||
"AccountV2" : {
|
||||
"type" : "object",
|
||||
"description" : "Account shape served by API version 2 — restructured, nested contact object",
|
||||
"properties" : {
|
||||
"accountId" : {
|
||||
"type" : "string",
|
||||
"description" : "Account identifier"
|
||||
},
|
||||
"displayName" : {
|
||||
"type" : "string",
|
||||
"description" : "Account holder display name"
|
||||
},
|
||||
"contact" : {
|
||||
"$ref" : "#/components/schemas/Contact",
|
||||
"description" : "Nested contact details, replacing the flat email field from 1.1"
|
||||
},
|
||||
"status" : {
|
||||
"type" : "string",
|
||||
"description" : "Lifecycle status, new in v2",
|
||||
"enum" : [ "ACTIVE", "SUSPENDED", "CLOSED" ]
|
||||
},
|
||||
"apiVersion" : {
|
||||
"type" : "string",
|
||||
"description" : "Echoes the resolved API version"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Contact" : {
|
||||
"type" : "object",
|
||||
"description" : "Contact details nested under an account, v2+",
|
||||
"properties" : {
|
||||
"email" : {
|
||||
"type" : "string",
|
||||
"description" : "Contact email"
|
||||
}
|
||||
}
|
||||
},
|
||||
"AccountV1" : {
|
||||
"type" : "object",
|
||||
"description" : "Account shape served by API version 1",
|
||||
"properties" : {
|
||||
"id" : {
|
||||
"type" : "string",
|
||||
"description" : "Account identifier"
|
||||
},
|
||||
"name" : {
|
||||
"type" : "string",
|
||||
"description" : "Account holder name"
|
||||
},
|
||||
"apiVersion" : {
|
||||
"type" : "string",
|
||||
"description" : "Echoes the resolved API version"
|
||||
}
|
||||
}
|
||||
},
|
||||
"AccountV1Point1" : {
|
||||
"type" : "object",
|
||||
"description" : "Account shape served from API version 1.1 onward (baseline handler)",
|
||||
"properties" : {
|
||||
"id" : {
|
||||
"type" : "string",
|
||||
"description" : "Account identifier"
|
||||
},
|
||||
"name" : {
|
||||
"type" : "string",
|
||||
"description" : "Account holder name"
|
||||
},
|
||||
"email" : {
|
||||
"type" : "string",
|
||||
"description" : "Contact email, added in 1.1"
|
||||
},
|
||||
"apiVersion" : {
|
||||
"type" : "string",
|
||||
"description" : "Echoes the resolved API version"
|
||||
}
|
||||
}
|
||||
},
|
||||
"ServerResponse" : { }
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
GET /v3/api-docs/accounts-v1 -> operationId=getAccountV1, schema=#/components/schemas/AccountV1, params=[id]
|
||||
GET /v3/api-docs/accounts-v1.1 -> operationId=getAccountV1Point1Plus, schema=#/components/schemas/AccountV1Point1, params=[id]
|
||||
GET /v3/api-docs/accounts-v2 -> operationId=getAccountV2, schema=#/components/schemas/AccountV2, params=[id]
|
||||
|
||||
Each group's VersionedOpenApiConfig#collapseToSingleVersion customizer rewrites the same
|
||||
merged oneOf operation shown in 02-what-springdoc-actually-generates.txt down to exactly
|
||||
one schema and drops the now-meaningless API-Version header — the default (ungrouped)
|
||||
/v3/api-docs document is completely unaffected, confirmed by re-fetching it below:
|
||||
|
||||
200
|
||||
{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:36991","description":"Generated server url"}],"paths":{"/accounts/{id}":{"get":{"tags":["account-controller"],"operationId":"getAccountV2","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"API-Version","in":"header","schema":{"type":"string","default":"1.0.0","enum":["2","1","1.0.0","1.1"]}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AccountV1"},{"$ref":"#/components/schemas/AccountV2"},{"$ref":"#/components/schemas/AccountV1Point1"}]}}}}}}},"/widgets/{id}":{"get":{"tags":["widget-handler"],"operationId":"getWidgetV1","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ServerResponse"}}}}}}}},"components":{"schemas":{"AccountV2":{"type":"object","description":"Account shape served by API version 2 — restructured, nested contact object","properties":{"accountId":{"type":"string","description":"Account identifier"},"displayName":{"type":"string","description":"Account holder display name"},"contact":{"$ref":"#/components/schemas/Contact","description":"Nested contact details, replacing the flat email field from 1.1"},"status":{"type":"string","description":"Lifecycle status, new in v2","enum":["ACTIVE","SUSPENDED","CLOSED"]},"apiVersion":{"type":"string","description":"Echoes the resolved API version"}}},"Contact":{"type":"object","description":"Contact details nested under an account, v2+","properties":{"email":{"type":"string","description":"Contact email"}}},"AccountV1":{"type":"object","description":"Account shape served by API version 1","properties":{"id":{"type":"string","description":"Account identifier"},"name":{"type":"string","description":"Account holder name"},"apiVersion":{"type":"string","description":"Echoes the resolved API version"}}},"AccountV1Point1":{"type":"object","description":"Account shape served from API version 1.1 onward (baseline handler)","properties":{"id":{"type":"string","description":"Account identifier"},"name":{"type":"string","description":"Account holder name"},"email":{"type":"string","description":"Contact email, added in 1.1"},"apiVersion":{"type":"string","description":"Echoes the resolved API version"}}},"ServerResponse":{}}}}
|
||||
@@ -0,0 +1,29 @@
|
||||
Runtime (Framework 7 RequestPredicates.version(...), routing is correct):
|
||||
GET /widgets/7, API-Version: 1 -> 200
|
||||
{"apiVersion":"1","id":"7"}
|
||||
GET /widgets/7, API-Version: 2 -> 200
|
||||
{"apiVersion":"2","widgetId":"7"}
|
||||
|
||||
springdoc documentation for the SAME path (2 @RouterOperation entries registered,
|
||||
one per version, via @RouterOperations on the RouterFunction bean):
|
||||
{
|
||||
"tags" : [ "widget-handler" ],
|
||||
"operationId" : "getWidgetV1",
|
||||
"responses" : {
|
||||
"200" : {
|
||||
"description" : "OK",
|
||||
"content" : {
|
||||
"*/*" : {
|
||||
"schema" : {
|
||||
"$ref" : "#/components/schemas/ServerResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Only ONE @RouterOperation survived (operationId=getWidgetV1) — the second is silently absent, not merged into a oneOf the way the annotated
|
||||
@GetMapping handlers were in 02-what-springdoc-actually-generates.txt. The response schema
|
||||
also did not resolve to either AccountV1-style record — it fell back to "#/components/schemas/ServerResponse" (springdoc introspecting the handler method's own ServerResponse return type,
|
||||
since @RouterOperation has no version attribute and I added no explicit operation() override).
|
||||
Reference in New Issue
Block a user