lhotari opened a new pull request, #25937: URL: https://github.com/apache/pulsar/pull/25937
PIP: [PIP-472](https://github.com/apache/pulsar/blob/master/pip/pip-472.md) (follow-up: completes the Swagger migration that PIP-472 explicitly deferred) ### Motivation PIP-472 migrated Pulsar from `javax.*` to `jakarta.*` but deferred the Swagger migration ("Swagger 1.x -> Swagger Core 2.x is deferred to a follow-up (decoupled, compile-/doc-only)"). Pulsar still depended on Swagger 1.6.2 (`io.swagger:*`), which is end-of-life, javax-era, and incompatible with the jakarta REST tier. In addition, OpenAPI document generation (the `swagger.json` files published as the REST API reference on pulsar.apache.org) had no equivalent in the Gradle build after the Maven removal. This PR migrates all Swagger annotations to Swagger Core v3 (`io.swagger.core.v3:swagger-annotations-jakarta:2.2.50`, OpenAPI 3) and restores spec generation via the official `io.swagger.core.v3.swagger-gradle-plugin`. ### Modifications **Annotation migration (61 Java files)** - `@Api` -> `@Tag` (+`@Hidden` where v1 had `hidden=true`), `@ApiOperation` -> `@Operation`, `@ApiResponse(code=, message=, response=, responseContainer=)` -> `@ApiResponse(responseCode=, description=, content=)` with `@ArraySchema`/`additionalPropertiesSchema` container mappings, `@ApiParam` -> `@Parameter` (bound params incl. `@FormDataParam` multipart parts) / `@RequestBody` (body params), `@ApiModel`/`@ApiModelProperty` -> `@Schema` with `requiredMode`, `@Example`/`@ExampleProperty` -> `@ExampleObject`. - Map-valued responses use `@Schema(type = "object", additionalPropertiesSchema = X.class)` — the only form the swagger-core 2.2.50 resolver renders correctly; the `@Content`-level `additionalPropertiesSchema = @Schema(implementation = X.class)` form silently emits an empty value schema. - Protobuf/lightproto types in `@Schema(implementation=)` replaced with `type = "object"` schemas (Jackson introspection crashes on them; those endpoints emit protobuf JSON). - `BaseGenerateDocumentation` reflection ported to `@Schema`; removed the unused `NoSwaggerDocumentation` marker and stale workaround comments for swagger-core#449 / swagger-ui#558 (both fixed upstream); nested map schemas are now expressed precisely. - Fixed malformed example JSON payloads and cleaned up typos/whitespace/grammar in annotation descriptions (separate commits). **Build** - Version catalog: `swagger = 2.2.50`, `swagger-annotations` -> `io.swagger.core.v3:swagger-annotations-jakarta`; removed the unused `swagger-core` alias. - New `io.swagger.core.v3.swagger-gradle-plugin` (2.2.50) configuration in `pulsar-broker` replicating the Maven `swagger` profile from branch-4.2: 7 resolve tasks with the same output file names and base info/servers, assembled by `./gradlew :pulsar-broker:generateOpenApiSpecs` into `build/openapi/` with the flat + `v2/` + `v3/` layout published on pulsar.apache.org. The plugin's default javax resolver dependencies are replaced with `swagger-jaxrs2-jakarta` via the `swaggerDeps` configuration. - `pulsar-docs-tools`, `pulsar-websocket` and `pulsar-client-tools` now declare guava/commons-lang3 explicitly (previously leaked onto the compile classpath via swagger-core 1.x transitives). - `io.kubernetes:client-java`'s transitive Swagger 1.x annotations are excluded: they are inert metadata on the generated k8s models (verified — no `Methodref`/`Fieldref` to `io.swagger` in any class of either jar; the JVM ignores missing annotation types during reflection). The k8s-exercising test suites pass with the exclusion. - Shade include pattern updated to the `io.swagger.core.v3` group; `LICENSE.bin.txt` updated for both distributions. ### Verifying this change - [x] Make sure that the change passes the CI checks. This change is already covered by existing tests and verified as follows: - The generated OpenAPI documents are operation-identical with the published 4.2.1 REST API docs: 597/597 operations across all 7 documents, zero drift; map-valued responses render the same `additionalProperties` value schemas as 4.2.1. - Every annotated REST resource class in the repo (broker, functions worker, websocket, proxy) was run through the real swagger-core resolver to prove it scans cleanly (`@Hidden` classes excluded by design, matching 1.x behavior). - `checkBinaryLicense` passes for the server and shell distributions; full `compileTestJava`, checkstyle, spotless and `pulsar-docs-tools` tests pass; the kubernetes-client-dependent test suites (`pulsar-functions-runtime`, `pulsar-functions-secrets`, `pulsar-broker-auth-oidc`) pass with the swagger-annotations exclusion. ### Does this pull request potentially affect one of the following parts: *If the box was checked, please highlight the changes* - [x] Dependencies (add or upgrade a dependency) - [ ] The public API - [ ] The schema - [ ] The default values of configurations - [ ] The threading model - [ ] The binary protocol - [ ] The REST endpoints - [ ] The admin CLI options - [ ] The metrics - [ ] Anything that affects deployment Dependency changes: `io.swagger:swagger-annotations/swagger-core 1.6.2` removed; `io.swagger.core.v3:swagger-annotations-jakarta 2.2.50` added (annotations only, no transitive deps); `io.swagger:swagger-annotations` excluded from `io.kubernetes:client-java`. REST endpoint *behavior* is unchanged — only the documentation annotations on the resource classes changed. As noted in PIP-472's compatibility section, authors of plugins that contribute JAX-RS resources using Swagger 1.x annotations need to migrate to `io.swagger.v3.oas.annotations.*` when recompiling against this version. Assisted-by: Claude Code (Opus 4.8) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
