[v2.5.0] Generic error responses from multiple @ControllerAdvice are still nondeterministic across OS

[karimkod]

Describe the bug

When two @ControllerAdvice classes handle overlapping HTTP status codes (e.g., both handle 500) but return different response types, the generated OpenAPI spec differs depending on the OS. The error response schema picked by springdoc is nondeterministic across operating systems.

This was reported and fixed in #53 (v1.1.26), but the issue seems to regressed or was not fully resolved in the v2.x line.

To Reproduce

• Spring Boot: 3.2.2
• springdoc-openapi: springdoc-openapi-starter-webmvc-ui:2.5.0
• Java: 17 (Azul Zulu 17.0.18)

Steps to reproduce:

1. Define two @ControllerAdvice classes with overlapping status codes but different return types:

@ControllerAdvice
public class HandlerA {
    @ExceptionHandler(CustomInternalException.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ResponseEntity<ErrorMessage> handle(CustomInternalException ex) {
        return new ResponseEntity<>(new ErrorMessage(ex.getStatus(), ex.getMessage()), ex.getStatus());
    }
}

@ControllerAdvice
public class HandlerB {
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ResponseEntity<ApiErrorException> handle(Exception ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ApiErrorException(ApiError.builder().status(HttpStatus.INTERNAL_SERVER_ERROR).message(ex.getMessage()).build()));
    }
}

2. Generate the OpenAPI spec on Linux/macOS → error responses reference ErrorMessage
3. Generate the same spec on Windows → error responses reference ApiErrorException

Actual result (on Windows):

"500": {
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ApiErrorException"
      }
    }
  }
}

Actual result (on Linux/macOS):

"500": {
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ErrorMessage"
      }
    }
  }
}

Expected behavior

The generated OpenAPI spec should be deterministic and identical regardless of the OS. When multiple @ControllerAdvice classes declare overlapping status codes, the resolution order should be stable and not depend on the underlying filesystem's directory listing order or internal Set iteration order.

Additional context

• Original issue: Generic (error) responses built from ControllerAdvice are nondeterministic #53 (fixed in v1.1.26 via commit da51f64)
• The issue appears to stem from the same root cause: non-deterministic iteration when building generic error responses from @ControllerAdvice exception handlers
• Tested and reproduced consistently: every run on Windows produces ApiErrorException, every run on Linux/macOS produces ErrorMessage

[karimkod]

Update: Upgrading Spring Boot and springdoc-openapi resolves the issue.

We upgraded the following dependencies:

• Spring Boot 3.2.2 → 3.4.3
• springdoc-openapi 2.5.0 → 2.8.6
• Spring Cloud 2023.0.2 → 2024.0.1

After the upgrade, we still have the same issue.