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

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

Start with openai-java-core/build.gradle.kts and inspect how swagger-annotations is exposed, then review the structured-output schema integration and its dependency metadata. Confirm the change against the published dependency graph so consumers using swagger-annotations-jakarta are not forced to receive the javax-oriented artifact while documented schema annotations remain supported.