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

Bắt đầu với openai-java-core/build.gradle.kts và kiểm tra cách swagger-annotations được cung cấp, sau đó xem xét tích hợp schema cho đầu ra có cấu trúc và metadata về dependency của nó. Xác nhận thay đổi dựa trên dependency graph đã được công bố để những consumer sử dụng swagger-annotations-jakarta không bị buộc phải nhận artifact hướng đến javax, đồng thời các schema annotation đã được ghi lại vẫn được hỗ trợ.

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