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

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