swagger-annotations api dependency conflicts with swagger-annotations-jakarta

Inizia da openai-java-core/build.gradle.kts e verifica come viene esposto swagger-annotations, quindi esamina l’integrazione dello schema per l’output strutturato e i relativi metadati delle dipendenze. Conferma la modifica rispetto al grafo delle dipendenze pubblicato, in modo che i consumer che usano swagger-annotations-jakarta non siano costretti a ricevere l’artefatto orientato a javax, mantenendo al contempo il supporto per le annotazioni dello schema documentate.

Description

openai-java-core declares:

api("io.swagger.core.v3:swagger-annotations:2.2.31")

(openai-java-core/build.gradle.kts)

This pulls the javax-oriented Swagger annotations artifact onto every consumer classpath as a hard dependency.

Many Jakarta EE / Spring Boot 3 applications already depend on io.swagger.core.v3:swagger-annotations-jakarta (e.g. via springdoc-openapi). Those two artifacts are mutually exclusive: they share the package io.swagger.v3.oas.annotations, so having both on the classpath causes duplicate-class / split-package conflicts.

Why this is surprising

The SDK itself does not need these annotations at compile time for its own types. Structured Outputs uses com.github.victools:jsonschema-module-swagger-2, which already declares swagger-annotations as provided. The annotations are only needed when consumers annotate their schema classes with @Schema / @ArraySchema (as documented in the README).

Re-exporting them as api is convenient, but it forces one of two incompatible coordinates onto ecosystems that already chose the other.

Workaround

Exclude the transitive dependency and keep the jakarta artifact:

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <exclusions>
    <exclusion>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-annotations</artifactId>
    </exclusion>
  </exclusions>
</dependency>

implementation("com.openai:openai-java:…") {
  exclude(group = "io.swagger.core.v3", module = "swagger-annotations")
}

Environment

• Consumer using swagger-annotations-jakarta (Spring Boot 3 / springdoc)
• openai-java bringing swagger-annotations via openai-java-core