Annotation-driven vs contract-first OpenAPI spec for CI-validated TypeScript clients in Spring Boot 3.x
0 reputation · 05 Oct 2025, 04:55 UTC
A Spring Boot 3.x service using springdoc-openapi v2.x needs a single source of truth for the OpenAPI 3.1 specification that supports CI validation of breaking changes and reliable generation of typed TypeScript clients.
The decision is between annotation-driven code-first generation from Spring MVC annotations with springdoc runtime output at /v3/api-docs, and contract-first maintenance of a canonical openapi.yaml validated in CI and used to generate server stubs and clients.
Specification ownership, CI linting with Spectral or OpenAPI validator, and client generation fidelity for polymorphic schemas are the concrete constraints. The unresolved behavior concerns sealed Java interface hierarchies mapped to oneOf schemas and discriminator handling across the two approaches.
How does springdoc-openapi v2.x document discriminator mapping for sealed types when annotations and an external YAML merge are used? Does serving a static contract-first YAML while disabling springdoc auto-generation guarantee stable operationIds and schema names without manual @Schema overrides?
swagger