[Feature]: Provide a BOM module for managing dependencies (#4966)

.github/workflows/maven-pulls.yml

@@ -29,6 +29,16 @@ jobs:
         key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
         restore-keys: |
           ${{ runner.os }}-maven-
+    - name: Check swagger-bom version matches root version
+      run: |
+        ROOT_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec)
+        BOM_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec --file modules/swagger-bom/pom.xml)
+        echo "Root version: ${ROOT_VERSION}"
+        echo "BOM version:  ${BOM_VERSION}"
+        if [ "${ROOT_VERSION}" != "${BOM_VERSION}" ]; then
+          echo "ERROR: swagger-bom version (${BOM_VERSION}) does not match root version (${ROOT_VERSION}). Update modules/swagger-bom/pom.xml."
+          exit 1
+        fi
     - name: Build with Maven and Gradle
       run: |
         ./mvnw --no-transfer-progress -B install --file pom.xml

.github/workflows/maven.yml

@@ -29,6 +29,16 @@ jobs:
         key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
         restore-keys: |
           ${{ runner.os }}-maven-
+    - name: Check swagger-bom version matches root version
+      run: |
+        ROOT_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec)
+        BOM_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec --file modules/swagger-bom/pom.xml)
+        echo "Root version: ${ROOT_VERSION}"
+        echo "BOM version:  ${BOM_VERSION}"
+        if [ "${ROOT_VERSION}" != "${BOM_VERSION}" ]; then
+          echo "ERROR: swagger-bom version (${BOM_VERSION}) does not match root version (${ROOT_VERSION}). Update modules/swagger-bom/pom.xml."
+          exit 1
+        fi
     - name: Build with Maven and Gradle, Deploy snapshot to maven central
       run: |
         export MY_POM_VERSION=`./mvnw -q -Dexec.executable="echo" -Dexec.args='${projects.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec`

.github/workflows/prepare-release.yml

@@ -35,6 +35,16 @@ jobs:
         key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
         restore-keys: |
           ${{ runner.os }}-maven-
+    - name: Check swagger-bom version matches root version
+      run: |
+        ROOT_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec)
+        BOM_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec --file modules/swagger-bom/pom.xml)
+        echo "Root version: ${ROOT_VERSION}"
+        echo "BOM version:  ${BOM_VERSION}"
+        if [ "${ROOT_VERSION}" != "${BOM_VERSION}" ]; then
+          echo "ERROR: swagger-bom version (${BOM_VERSION}) does not match root version (${ROOT_VERSION}). Update modules/swagger-bom/pom.xml."
+          exit 1
+        fi
     - name: Run prepare release script
       id: prepare-release
       run: |

.github/workflows/release.yml

@@ -40,6 +40,16 @@ jobs:
       run: |
         mkdir -p ~/.gradle
         echo "gradle.publish.key=${GRADLE_PUBLISH_KEY}\ngradle.publish.secret=${GRADLE_PUBLISH_SECRET}" > ~/.gradle/gradle.properties
+    - name: Check swagger-bom version matches root version
+      run: |
+        ROOT_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec)
+        BOM_VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.3.1:exec --file modules/swagger-bom/pom.xml)
+        echo "Root version: ${ROOT_VERSION}"
+        echo "BOM version:  ${BOM_VERSION}"
+        if [ "${ROOT_VERSION}" != "${BOM_VERSION}" ]; then
+          echo "ERROR: swagger-bom version (${BOM_VERSION}) does not match root version (${ROOT_VERSION}). Update modules/swagger-bom/pom.xml."
+          exit 1
+        fi
     - name: Run pre release script
       id: preRelease
       run: |

CI/post-release.sh

@@ -23,6 +23,11 @@ python $CUR/CI/publishRelease.py "$SC_RELEASE_TAG"
 ./mvnw versions:set -DnewVersion="${SC_NEXT_VERSION}-SNAPSHOT"
 ./mvnw versions:commit
 
+cd modules/swagger-bom
+../../mvnw versions:set -DnewVersion="${SC_NEXT_VERSION}-SNAPSHOT"
+../../mvnw versions:commit
+cd ../..
+
 cd modules/swagger-project-jakarta
 ../../mvnw versions:set -DnewVersion="${SC_NEXT_VERSION}-SNAPSHOT"
 ../../mvnw versions:commit

CI/prepare-release.sh

@@ -25,6 +25,11 @@ python $CUR/CI/releaseNotes.py "$SC_LAST_RELEASE" "$SC_RELEASE_TITLE" "$SC_RELEA
 ./mvnw versions:set -DnewVersion=$SC_VERSION
 ./mvnw versions:commit
 
+cd modules/swagger-bom
+../../mvnw versions:set -DnewVersion=$SC_VERSION
+../../mvnw versions:commit
+cd ../..
+
 cd modules/swagger-project-jakarta
 ../../mvnw versions:set -DnewVersion=$SC_VERSION
 ../../mvnw versions:commit

README.md

@@ -156,6 +156,111 @@ Of course if you don't want to build locally you can grab artifacts from maven c
 
 `https://repo1.maven.org/maven2/io/swagger/core/`
 
+### Maven BOM
+
+The `swagger-bom` artifact is a Bill of Materials that manages **both** the `javax` and Jakarta (`-jakarta` suffix) artifact families.
+Import it once and omit versions on all individual Swagger dependencies.
+
+> **Note:** Maven and Gradle build plugins (`swagger-maven-plugin`, `swagger-gradle-plugin`,
+> `swagger-eclipse-transformer-maven-plugin`) are intentionally **excluded** from the BOM.
+> Plugins are applied via `<build><plugins>` or `plugins {}`, not via `<dependencyManagement>`,
+> so including them in the BOM would be misleading and could conflict with the plugin
+> management section of a consumer's build.
+
+#### Maven
+
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>io.swagger.core.v3</groupId>
+      <artifactId>swagger-bom</artifactId>
+      <version>${swagger-openapiv3.version}</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+
+<!-- Then declare Swagger dependencies without explicit versions -->
+<dependencies>
+  <!-- javax artifacts -->
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-annotations</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-models</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-core</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-integration</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
+  </dependency>
+  <!-- Jakarta namespace artifacts (use instead of, or alongside, the javax ones above) -->
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-annotations-jakarta</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-models-jakarta</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-core-jakarta</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-integration-jakarta</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-jakarta</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-servlet-initializer-jakarta</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>io.swagger.core.v3</groupId>
+    <artifactId>swagger-jaxrs2-servlet-initializer-v2-jakarta</artifactId>
+  </dependency>
+</dependencies>
+```
+
+#### Gradle
+
+```kotlin
+dependencies {
+    implementation(platform("io.swagger.core.v3:swagger-bom:${swaggerOpenapiv3Version}"))
+
+    // javax artifacts — no version needed
+    implementation("io.swagger.core.v3:swagger-annotations")
+    implementation("io.swagger.core.v3:swagger-core")
+
+    // Jakarta namespace artifacts — no version needed
+    implementation("io.swagger.core.v3:swagger-annotations-jakarta")
+    implementation("io.swagger.core.v3:swagger-core-jakarta")
+}
+```
+
 ## Sample Apps
 The samples have moved to [a new repository](https://github.com/swagger-api/swagger-samples/tree/2.0) and contain various integrations and configurations.
 

modules/swagger-bom-integration-test/pom.xml

@@ -0,0 +1,141 @@
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.swagger.core.v3</groupId>
+        <artifactId>swagger-project</artifactId>
+        <version>2.2.47-SNAPSHOT</version>
+        <relativePath>../..</relativePath>
+    </parent>
+
+    <artifactId>swagger-bom-integration-test</artifactId>
+    <packaging>pom</packaging>
+
+    <name>swagger-bom-integration-test</name>
+    <description>Verifies that swagger-bom manages all expected artifacts at the correct version</description>
+
+    <!-- Not a publishable artifact -->
+    <properties>
+        <maven.deploy.skip>true</maven.deploy.skip>
+        <maven.install.skip>true</maven.install.skip>
+    </properties>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>io.swagger.core.v3</groupId>
+                <artifactId>swagger-bom</artifactId>
+                <version>${project.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+    <!--
+        Declare every artifact the BOM is expected to manage, without explicit versions.
+        Maven will fail if the BOM does not provide a version for any of these entries.
+    -->
+    <dependencies>
+        <!-- javax artifact family -->
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-models</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-integration</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
+        </dependency>
+        <!-- Jakarta namespace artifact family -->
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations-jakarta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-models-jakarta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-core-jakarta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-integration-jakarta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2-jakarta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2-servlet-initializer-jakarta</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2-servlet-initializer-v2-jakarta</artifactId>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!--
+                Explicitly resolve all declared dependencies so that the build fails
+                fast if any managed artifact cannot be downloaded or is missing
+                from the local repository after a full reactor install.
+            -->
+            <!-- Disable the DependencyConvergence rule inherited from the root parent.
+                 Transitive deps of mixed javax/Jakarta artifacts intentionally diverge. -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-enforcer-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>enforce-versions</id>
+                        <configuration>
+                            <skip>true</skip>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>verify-bom-deps-resolve</id>
+                        <phase>validate</phase>
+                        <goals>
+                            <goal>resolve</goal>
+                        </goals>
+                        <configuration>
+                            <includeGroupIds>io.swagger.core.v3</includeGroupIds>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>