Skip to content

Manage the OpenAPI stack (springdoc, Swagger, Swagger UI) in dependencyManagement #6

Closed

Description

@herbie-bot

The parent manages springdoc-openapi-starter-webmvc-ui 2.8.17 but none of the
Swagger artifacts springdoc is built against, so Swagger floats and is resolved by
nearest-wins mediation in every consuming project.

When a library on the classpath contributes an older swagger-annotations-jakarta,
the stack does not become uniformly old — it splits. swagger-core-jakarta
2.2.47 arrives via springdoc while the annotations stay at 2.2.29, and Swagger's own
modules then call each other across incompatible versions:

io.swagger.v3.core.jackson.ModelResolver          (swagger-core-jakarta 2.2.47)
  invokeinterface io/swagger/v3/oas/annotations/media/Schema.$dynamicRef:()Ljava/lang/String;
                                                   exists in annotations 2.2.47
                                                   absent in annotations 2.2.29

That is a NoSuchMethodError. A consuming project hit exactly this and had to pin
springdoc back to 2.8.6, whose matching Swagger version is 2.2.29 — restoring a
uniform stack by accident rather than by design.

springdoc does not expose this coupling through anything it publishes:
springdoc-openapi-bom manages only the seven springdoc artifacts. The Swagger
version lives in springdoc's aggregator POM as <swagger-api.version> (2.8.6 →
2.2.29, 2.8.17 → 2.2.47).

Full technical design and behavioral scenarios:
docs/specs/003-openapi-stack-versions/

Acceptance criteria

  • pom.xml imports org.springdoc:springdoc-openapi-bom and
    io.swagger.core.v3:swagger-bom, and manages org.webjars:swagger-ui
  • springdoc.version, swagger.version and swagger-ui.version are documented
    as a coupled set, with the lookup path for future bumps
  • The explicit springdoc-openapi-starter-webmvc-ui entry is removed in favour
    of the BOM
  • A probe child that transitively receives swagger-annotations-jakarta 2.2.29
    resolves all three jakarta artifacts to 2.2.47
  • README documents the managed stack and the lockstep rule

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions