spring-boot-demo/openapi-versioning/docs/04-the-functional-endpoint-path.md

The functional-endpoint path: officially supported, and worse

springdoc-openapi's v3.0.2 release notes (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 to check.

Full transcript: docs/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:

@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

{
  "tags": ["widget-handler"],
  "operationId": "getWidgetV1",
  "responses": {
    "200": {
      "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ServerResponse" } } }
    }
  }
}

Two registered @RouterOperations 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.