Skip to content

Use Swagger BOM#3272

Open
michaldo wants to merge 1 commit intospringdoc:mainfrom
michaldo:use-swagger-bom
Open

Use Swagger BOM#3272
michaldo wants to merge 1 commit intospringdoc:mainfrom
michaldo:use-swagger-bom

Conversation

@michaldo
Copy link
Copy Markdown

This PR assumes that:

  1. Springdoc release is compatible with <swagger-api.version>
  2. Every application which use Springdoc wants compatible Swagger version and does not want risk incompatible Swagger version which may win automatic version resolution.

Additional bonus for Maven multi module application is that with given BOM one module may take dependency to io.swagger.core.v3:swagger-annotations and other module may take dependency to org.springdoc:springdoc-openapi-starter-webmvc-ui without version managements, because versions are managed by Springdoc BOM

This PR assumes that:
1. Springdoc release is compatible with `<swagger-api.version>`
2. Every application which use Springdoc wants compatible Swagger version and does not want risk incompatible Swagger version which may win automatic version resolution.

Additional bonus for Maven multi module application is that with given BOM one module may take dependency to `io.swagger.core.v3:swagger-annotations` and other module may take dependency to `org.springdoc:springdoc-openapi-starter-webmvc-ui` without version managements, because versions are managed by Springdoc BOM
@Mattias-Sehlstedt
Copy link
Copy Markdown
Contributor

Please see #3222 on the subject.

@michaldo
Copy link
Copy Markdown
Author

Please see #3222 on the subject.

This PR is created after #3271 and after reading discussion #3222

<properties>remove</properties>
<distributionManagement>remove</distributionManagement>
<dependencyManagement>keep</dependencyManagement>
<dependencyManagement>extended_interpolate</dependencyManagement>
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this change do?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question because answer is tricky.

Actually springdoc-openapi-bom-3.0.3.pom is flattened and reduced to minimum and it is fine.
But I added this section

<dependency>
  <groupId>io.swagger.core.v3</groupId>
  <artifactId>swagger-bom</artifactId>
  <version>${swagger-api.version}</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

If flatten-maven-plugin is untouched, <version>${swagger-api.version}</version> will remain ai-is and whole BOM will be unusable because ${swagger-api.version} is unknown (please notice <properties>remove</properties>)

I had 2 options:

  1. I could change to <properties>resolve</properties>. After that BOM will be populated by all properties defined in springdoc. BOM will be usable but awful - full of plenty completely useless properties - and I rejected option 1.
  2. I decided to upgrade flatten-maven-plugin and use extended_interpolate. After that BOM has still no property at all and all properties in BOM are replaced by concrete values.

I must admin I do not understand why plain interpolate failed and I had to upgrade flatten-maven-plugin to newer version and use extended_interpolate. Documentation of the plugin is fragmentary

Anyway, goal of the change is interpolate ${swagger-api.version} inside published BOM file and keep the file free from <properties> section

Copy link
Copy Markdown
Contributor

@Mattias-Sehlstedt Mattias-Sehlstedt Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me it looks like <flattenMode>bom</flattenMode> might be incompatible with <dependencyManagement>extended_interpolate</dependencyManagement>? Since it states that no import-scoped dependencies will be retained?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I mentioned, plugin documentation is fragmentary.
Config in PR is result of try and fails.
I focused rather on output flattened BOM file.

@Mattias-Sehlstedt
Copy link
Copy Markdown
Contributor

Is point two a recognition of this being a breaking change? My understanding of this change compared to other dependency suggestions (also aimed towards fixing potential compatibility issues between springdoc and swagger-core) is that this is doing exactly the same change? (and that it is a breaking change).

@michaldo
Copy link
Copy Markdown
Author

Is point two a recognition of this being a breaking change? My understanding of this change compared to other dependency suggestions (also aimed towards fixing potential compatibility issues between springdoc and swagger-core) is that this is doing exactly the same change? (and that it is a breaking change).

I do not understand precisely the question, but

  1. Comparing to zongruxie4@3de9d2d it is same change but more consistent, because I can utilize just added io.swagger.core.v3 BOM
  2. Is this breaking change? It is hard to answer
    It is easy to tell what is breaking change in code. But in dependencies? Every time new springdoc is released, dependencies like swagger are updated and it may break something.
    For example between 2.8.13 and 2.8.14 scalar was updated from 0.1.0 to 0.3.12. Was it a breaking change for project taking scalar dependency from springdoc? If 0.1.0 to 0.3.12 is breaking, then yes.
    For me it is very philosophical to discuss if transitive dependencies are part of breakable contract or implementation detail.

I do not want dig into Maven dependency precedence rules, because theoretically multiple combinations are possible.
My answer is:

If there were someone who wanted to use incompatible versions of swagger-core and springdoc, and "wrong" swagger-core version is declared in way that can be overridden by springdoc BOM - what is not easy to achieve - then for such a person this would be a breaking change—but such a person cannot exist.

As mentioned in discussion,

The Bill Of Material is a special POM file that groups dependency versions that are known to be valid and tested to work together.

Because swagger core version conflict is real, and springdoc completely depend on swagger and its version is critical, sprindoc BOM must include compatible swagger core version. And it does not prevent anyone from overwriting with incompatible version. But such a person cannot exist.

@michaldo
Copy link
Copy Markdown
Author

I think now I understand comment.

My PR will not fail like 3de9d2d
because I included <dependencyManagement>extended_interpolate</dependencyManagement>

@Mattias-Sehlstedt
Copy link
Copy Markdown
Contributor

I would not say that it is impossible that someone is using a swagger-core dependency that isn't Jakarta that is misaligned with springdoc's swagger-core-jakarta version. But yes it is highly unlikely, and especially it causing issues as well. I have said many times before "surely this should not affect anything", and then you get an uproar of complaints that you have broken someones workflow (even though their workflow was entirely based upon an unintentional behavior).

If anything the recent introduction of the bom itself would be the best motivation to why it could be extended/have a "breaking change" (I had previously missed to notice just how new it is), since the adoption rate could be assumed to be low.

But I am only a contributor to this repo. So any decision is as always up to the maintainer. I am merely curious how of these types of issues can be managed in an open-source context.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants