Annotation-driven vs contract-first OpenAPI spec for CI-validated TypeScript clients in Spring Boot 3.x

Answer

springdoc-openapi v2.x does not automatically create a discriminator mapping for a sealed Java interface hierarchy unless you add explicit annotations (e.g., @Schema with discriminatorProperty and @DiscriminatorMapping) on the sealed interface or its permitted subclasses. When you also provide an external openapi.yaml that springdoc merges in via a customizer bean, the merge order depends on bean initialization and can overwrite or discard the annotation‑derived oneOf/discriminator, leading to non‑deterministic output.

Confirmed facts

• springdoc v2.x generates the OpenAPI 3.1 document at runtime from Spring MVC annotations; sealed types appear as a plain oneOf without discriminator.mapping unless the annotations described above are present.
• If you disable springdoc auto‑generation (springdoc.api-docs.enabled=false) and serve a static openapi.yaml (e.g., from src/main/resources/META-INF/springdoc/openapi.yaml) the endpoint returns exactly that YAML, provided you expose it via a controller or springdoc.swagger-ui.url.
• When the static YAML defines explicit operationId values and schema titles (title/x‑name), those values are stable across builds and are not affected by Java refactoring; no @Schema overrides are required in the code.
• CI validation with Spectral or OpenAPI Validator is reliable against the static YAML because it is the single source of truth; annotation‑driven pipelines must first generate the spec (via springdoc:generate or an embedded server) before linting, which adds flakiness.

Likely explanation (based on observed behavior)

The merge performed by springdoc’s OpenAPI customizer processes annotation‑derived schemas first, then overlays the external YAML. Because the YAML may omit discriminator.mapping, the final spec can lose the mapping that annotations added, or vice‑versa, depending on which bean wins the merge. This non‑determinism is why many teams prefer a pure contract‑first approach for sealed types.

Verification steps (safe, scoped)

1. Check your springdoc version: mvn dependency:tree | grep springdoc-openapi (or Gradle equivalent).
2. To see what springdoc produces from annotations alone, run ./mvnw springdoc:generate and inspect target/openapi.json for a discriminator object under the sealed type’s oneOf.
3. To confirm static YAML is served unchanged, set springdoc.api-docs.enabled=false, place openapi.yaml in src/main/resources/META-INF/springdoc/, expose it via a simple @RestController returning ResponseEntity.ok(new ClassPathResource("META-INF/springdoc/openapi.yaml")), start the app and curl -s http://localhost:8080/v3/api-docs | head -20; compare the output to the file with diff.
4. For CI validation, run Spectral against the static YAML: spectral lint openapi.yaml -r spectral-oas and verify no breaking‑change rules fire.

Missing diagnostic detail

Please confirm the exact version of springdoc-openapi you are using (e.g., 2.0.0, 2.5.0) because discriminator inference changed between the 2.0.x and 2.5.x releases; the recommendation to rely on annotations versus static YAML may shift with newer patches.