Inconsistent injection of @ControllerAdvice responses into generated OpenAPI spec

[MiButnyk]

Short summary:
We see inconsistent behavior in how SpringDoc injects responses declared in a @ControllerAdvice into generated OpenAPI specs. Specifically: when generating with OAS 3.0.1 the spec contained 405 Method Not Allowed and other handler responses across operations; when generating with OAS 3.1.0 the 405 entry is absent from operations (unless the operation explicitly declares the corresponding exception), while 400/422/500 responses remain present on operations. Our project has springdoc.override-with-generic-response=true. We need an authoritative statement of intended behavior and guidance to produce stable, predictable OpenAPI output across SpringDoc versions.

Versions:
Previous
OAS 3.0.1
org.springdoc:springdoc-openapi-starter-webmvc-ui: 2.1.0

Current
OAS 3.1.0
org.springdoc:springdoc-openapi-starter-webmvc-ui: 2.8.3

Property: springdoc.override-with-generic-response=true. (We rely on this behavior to reflect @ControllerAdvice responses in generated specs.)

Minimal relevant code (exception handlers in our @ControllerAdvice)

@ExceptionHandler(ConstraintViolationException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
@ResponseBody
public BaseResponse handleConstraintViolationException(...) { ... }

@ExceptionHandler(HttpRequestMethodNotSupportedException.class)
@ResponseStatus(HttpStatus.METHOD_NOT_ALLOWED)
@ResponseBody
public BaseResponse handleHttpRequestMethodNotSupportedException(...) { ... }

Concrete observed behaviour

Under OAS 3.0.1 exports, responses from the @ControllerAdvice (including 405) were injected into all operations.

Under OAS 3.1.0 exports, 405 no longer appears on operations unless the operation explicitly declares/throws HttpRequestMethodNotSupportedException, but 400/422/500 responses (from other handlers) are still injected (corresponding exceptions are not explicitly declared/thrown).

This creates an inconsistent rule: some handler responses are treated as “global” while others are added only when SpringDoc can link them to a specific operation.

What public issues show:

Issue #2483 reported that exception handlers seem to be applied to all operations, even if the implementing operation method handler does not throw the exception handled by the exception handler. (reported for springdoc-openapi-starter-webmvc-ui:2.3.0), was recognized as a bug and fixed.

Issue #2908 reported that using @ExceptionHandler(ConstraintViolationException.class) resulted in 400 response being added to all operations but it wasn't recognized as a bug

Questions we need answered:

Why the difference between exception types: Why would HttpRequestMethodNotSupportedException (405) be excluded from all operations unless explicitly declared, while 400/422/500 responses are still appearing globally? Is there a deliberate distinction in the code that treats certain exception classes as “global by default”? If so, what is the exact classification and rationale?

OAS version differences: Are there any known differences in @ControllerAdvice responses injection between generating OAS 3.0.1 and OAS 3.1.0 that could explain the observed divergence?

If this is a bug: If the maintainers consider surprising asymmetric treatment between exception types/responses a bug - please fix it

[Mattias-Sehlstedt]

Under OAS 3.0.1 exports, responses from the @ControllerAdvice (including 405) were injected into all operations.

Under OAS 3.1.0 exports, 405 no longer appears on operations unless the operation explicitly declares/throws HttpRequestMethodNotSupportedException, but 400/422/500 responses (from other handlers) are still injected (corresponding exceptions are not explicitly declared/thrown).

Do we mean here that we have tried OAS 3.0.1 and 3.1.0 for springdoc 2.8.3? Or do we mean OAS 3.0.1 with the old version and OAS 3.1.0 with the later version?

If we have tried 3.0.1 only with the older version, then I believe it could be of interest to try OAS 3.0.1 with 2.8.3, to see if the issue is the specification version or the springdoc version. OAS 3.0.1 can be configured by setting springdoc.api-docs.version=openapi_3_0 in the properties.

[bnasslahsen]

@MiButnyk.

Not clear.
Feel free to provide the link to a git repo with Minimal, Reproducible Example - with HelloController that reproduces the problem.

Without any further explanation, the ticket will be closed, but can be reopened if your provide the reproducible sample.

[MiButnyk]

Do we mean here that we have tried OAS 3.0.1 and 3.1.0 for springdoc 2.8.3? Or do we mean OAS 3.0.1 with the old version and OAS 3.1.0 with the later version?
If we have tried 3.0.1 only with the older version, then I believe it could be of interest to try OAS 3.0.1 with 2.8.3, to see if the issue is the specification version or the springdoc version. OAS 3.0.1 can be configured by setting springdoc.api-docs.version=openapi_3_0 in the properties.

@Mattias-Sehlstedt Initially we checked OAS 3.0.1 with the old version and OAS 3.1.0 with the later version. Thank you for suggestion - we tried OAS 3.0.1 with 2.8.3 and result was the same as for OAS 3.1.0 with 2.8.3: 405 is absent unless explicitly declared, while 400/422/500 remain - so the issue is with the springdoc version

@bnasslahsen the reproducible sample will be provided asap