spring-boot-demo/openapi-versioning/docs/05-the-grouped-openapi-fix.md

The fix: one GroupedOpenApi per version

Full transcript: docs/output/05-grouped-openapi-fix.txt, from OpenApiVersioningTest#c_groupedOpenApiCustomizerCollapsesToOneCleanSchemaPerVersion.

VersionedOpenApiConfig 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:

@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 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.