#25 Cross build the project for springdoc-openapi v2.x (#27)

Author: jakipatryk

.github/workflows/ci_code_coverage.yml

@@ -14,27 +14,49 @@ jobs:
       - name: Setup Scala
         uses: olafurpg/setup-scala@v14
         with:
-          java-version: "adopt@1.8"
-      - name: Build, run tests, and generate Jacoco code coverage report
-        run: sbt ++2.12.18 jacoco
-      - name: Add coverage to PR
-        id: jacoco
+          java-version: "openjdk@1.17.0"
+      - name: Build, run tests, and generate Jacoco code coverage report for springdoc-openapi-scala (all subversions)
+        run: sbt jacoco
+      - name: Add coverage to PR for springdoc-openapi-scala-1
+        id: jacoco1
         uses: madrapps/[email protected]
         with:
           paths: >
-            ${{ github.workspace }}/target/scala-2.12/jacoco/report/jacoco.xml
+            ${{ github.workspace }}/library/target/1-jvm-2.12/jacoco/report/jacoco.xml
           token: ${{ secrets.GITHUB_TOKEN }}
           min-coverage-overall: 0.0
           min-coverage-changed-files: 80.0
-          title: JaCoCo code coverage report - springdoc-openapi-scala
+          title: JaCoCo code coverage report - springdoc-openapi-scala-1
           update-comment: true
           debug-mode: true
-      - name: Get the Coverage info
+      - name: Add coverage to PR for springdoc-openapi-scala-2
+        id: jacoco2
+        uses: madrapps/[email protected]
+        with:
+          paths: >
+            ${{ github.workspace }}/library/target/2-jvm-2.12/jacoco/report/jacoco.xml
+          token: ${{ secrets.GITHUB_TOKEN }}
+          min-coverage-overall: 0.0
+          min-coverage-changed-files: 80.0
+          title: JaCoCo code coverage report - springdoc-openapi-scala-2
+          update-comment: true
+          debug-mode: true
+      - name: Get the Coverage info for springdoc-openapi-scala-1
+        run: |
+          echo "Total coverage ${{ steps.jacoco1.outputs.coverage-overall }}"
+          echo "Changed Files coverage ${{ steps.jacoco1.outputs.coverage-changed-files }}"
+      - name: Get the Coverage info for springdoc-openapi-scala-2
         run: |
-          echo "Total coverage ${{ steps.jacoco.outputs.coverage-overall }}"
-          echo "Changed Files coverage ${{ steps.jacoco.outputs.coverage-changed-files }}"
-      - name: Fail PR if changed files coverage is less than 80%
-        if: ${{ steps.jacoco.outputs.coverage-changed-files < 80.0 }}
+          echo "Total coverage ${{ steps.jacoco2.outputs.coverage-overall }}"
+          echo "Changed Files coverage ${{ steps.jacoco2.outputs.coverage-changed-files }}"
+      - name: Fail PR if changed files coverage is less than 80% for springdoc-openapi-scala-1
+        if: ${{ steps.jacoco1.outputs.coverage-changed-files < 80.0 }}
+        uses: actions/[email protected]
+        with:
+          script: |
+            core.setFailed('Changed files coverage is less than 80%!')
+      - name: Fail PR if changed files coverage is less than 80% for springdoc-openapi-scala-2
+        if: ${{ steps.jacoco2.outputs.coverage-changed-files < 80.0 }}
         uses: actions/[email protected]
         with:
           script: |

.github/workflows/ci_tests.yml

@@ -23,18 +23,13 @@ on:
 jobs:
   tests:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        scala: [2.12.18, 2.13.12]
-    name: Scala ${{matrix.scala}}
     steps:
       - name: Checkout code
         uses: actions/[email protected]
       - uses: coursier/cache-action@v6
       - name: Setup Scala
         uses: olafurpg/setup-scala@v14
         with:
-          java-version: "adopt@1.8"
+          java-version: "openjdk@1.17.0"
       - name: Build and run tests
-        run: sbt ++${{matrix.scala}} clean test
+        run: sbt clean test

README.md

@@ -24,25 +24,45 @@ This library aims to avoid pollution of the model by custom annotations and depe
 
 ## Usage
 
+springdoc-openapi-scala supports two major versions of springdoc-openapi: 1.x and 2.x.
+
 ### Provided dependencies
-The library has `"org.springdoc" % "springdoc-openapi-webmvc-core"` as a provided dependency, 
-thus users of the library have to include that dependency in their projects.
-Versions `1.6.7` up to `1.7.0` (including) are supported.
+The library has springdoc-openapi as a provided dependency, 
+thus users of the library have to include that dependency in their projects:
+- for springdoc-openapi 1.x versions `1.6.7` up to `1.7.0` (including) of 
+`"org.springdoc" % "springdoc-openapi-webmvc-core"` are supported
+- for springdoc-openapi 2.x versions `1.6.7` up to `1.7.0` (including) of
+`"org.springdoc" % "springdoc-openapi-starter-webmvc-api"` are supported
 
 ### Add library dependency to SBT/Maven
-SBT:
+#### SBT
+If you want to use the library with springdoc-openapi 1.x, add:
+```sbt
+libraryDependencies ++= Seq("za.co.absa" %% "springdoc-openapi-scala-1" % VERSION)
+```
+if with springdoc-openapi 2.x, add:
 ```sbt
-libraryDependencies ++= Seq("za.co.absa" %% "springdoc-openapi-scala" % VERSION)
+libraryDependencies ++= Seq("za.co.absa" %% "springdoc-openapi-scala-2" % VERSION)
 ```
 
-Maven:
+#### Maven
+If you want to use the library with springdoc-openapi 1.x, add:
+```xml
+<dependency>
+   <groupId>za.co.absa</groupId>
+   <artifactId>springdoc-openapi-scala-1_{scala_binary_version}</artifactId>
+   <version>${version}</version>
+</dependency>
+```
+if with springdoc-openapi 2.x, add:
 ```xml
 <dependency>
    <groupId>za.co.absa</groupId>
-   <artifactId>springdoc-openapi-scala_{scala_binary_version}</artifactId>
+   <artifactId>springdoc-openapi-scala-2_{scala_binary_version}</artifactId>
    <version>${version}</version>
 </dependency>
 ```
+
 where `scala_binary_version` is either `2.12` or `2.13`.
 
 ### Create custom OpenAPI Spring Configuration
@@ -102,13 +122,13 @@ class ExampleController @Autowired()(openAPIModelRegistration: OpenAPIModelRegis
 
 ## Examples
 
-### Simple example
-Can be found in this repo: [link](examples/simple). It generates the following OpenAPI JSON doc:
+### Simple example for springdoc-openapi-scala-1
+Can be found in this repo: [link](examples/springdoc-openapi-scala-1/simple). It generates the following OpenAPI JSON doc:
 ```json
 {
     "openapi": "3.0.1",
     "info": {
-        "title": "Example API",
+        "title": "Example API with springdoc-openapi v1.x",
         "version": "1.0.0"
     },
     "servers": [
@@ -192,3 +212,116 @@ Can be found in this repo: [link](examples/simple). It generates the following O
     }
 }
 ```
+
+### Simple example for springdoc-openapi-scala-2
+Can be found in this repo: [link](examples/springdoc-openapi-scala-2/simple). It generates the following OpenAPI JSON doc:
+```json
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "Example API with springdoc-openapi v2.x",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "http://localhost:8080",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/api/v1/example/some-endpoint": {
+      "post": {
+        "tags": [
+          "example-controller"
+        ],
+        "operationId": "someEndpoint",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExampleModelRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExampleModelResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/example/empty-endpoint": {
+      "post": {
+        "tags": [
+          "example-controller"
+        ],
+        "operationId": "emptyEndpoint",
+        "responses": {
+          "204": {
+            "description": "No Content"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "ExampleModelRequest": {
+        "required": [
+          "a",
+          "b",
+          "d"
+        ],
+        "properties": {
+          "a": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "b": {
+            "type": "string"
+          },
+          "c": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "d": {
+            "type": "string",
+            "enum": [
+              "OptionC",
+              "OptionB",
+              "OptionA"
+            ]
+          }
+        }
+      },
+      "ExampleModelResponse": {
+        "required": [
+          "d",
+          "e"
+        ],
+        "properties": {
+          "d": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int32"
+            }
+          },
+          "e": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}
+```

build.sbt

@@ -14,37 +14,18 @@
  * limitations under the License.
  */
 
+import SpringdocOpenAPIVersionAxis._
 import Dependencies._
-import com.github.sbt.jacoco.report.JacocoReportSettings
 
 ThisBuild / organization := "za.co.absa"
 ThisBuild / scalaVersion := Versions.scala212
 ThisBuild / versionScheme := Some("early-semver")
 
 lazy val supportedScalaVersions = List(Versions.scala212, Versions.scala213)
 
-lazy val commonJacocoReportSettings: JacocoReportSettings = JacocoReportSettings(
-  formats = Seq(JacocoReportFormats.HTML, JacocoReportFormats.XML)
-)
-
-lazy val commonJacocoExcludes: Seq[String] = Seq(
-//  "za.co.absa.springdocopenapiscala.*"
-)
-
-lazy val root = (project in file("."))
-  .settings(
-    name := "springdoc-openapi-scala",
-    libraryDependencies ++= libraryDependencyList(scalaVersion.value),
-    crossScalaVersions := supportedScalaVersions,
-    jacocoReportSettings := commonJacocoReportSettings.withTitle(s"SpringDoc OpenApi - scala:${scalaVersion.value}"),
-    jacocoExcludes := commonJacocoExcludes
-  )
-
-lazy val simpleExample = (project in file("examples/simple"))
+lazy val `springdoc-openapi-scala` = (projectMatrix in file("library"))
   .settings(
-    libraryDependencies ++= exampleProjectsDependencyList,
-    webappWebInfClasses := true,
-    inheritJarManifest := true
+    name := "springdoc-openapi-scala"
   )
-  .enablePlugins(TomcatPlugin)
-  .dependsOn(root)
+  .row(SpringdocOpenAPIVersionAxis(1), supportedScalaVersions)
+  .row(SpringdocOpenAPIVersionAxis(2), supportedScalaVersions)

examples/springdoc-openapi-scala-1/simple/build.sbt

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2023 ABSA Group Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+ThisBuild / scalaVersion := "2.12.18"
+
+lazy val `springdoc-openapi-scala-1-version`: String = ??? // specify version of the library, for example "0.2.0"
+
+lazy val root = (project in file("."))
+  .settings(
+    libraryDependencies ++= Seq(
+      "za.co.absa" %% "springdoc-openapi-scala-1" % `springdoc-openapi-scala-1-version`,
+      "org.springdoc" % "springdoc-openapi-webmvc-core" % "1.7.0",
+      "org.springframework.boot" % "spring-boot-starter-web" % "2.6.6"
+    ),
+    webappWebInfClasses := true,
+    inheritJarManifest := true
+  )
+  .enablePlugins(TomcatPlugin)

examples/springdoc-openapi-scala-1/simple/project/build.properties

@@ -0,0 +1 @@
+sbt.version = 1.9.7

examples/springdoc-openapi-scala-1/simple/project/plugins.sbt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2023 ABSA Group Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+addSbtPlugin("com.earldouglas" % "xsbt-web-plugin" % "4.2.4")

examples/simple/src/main/scala/za/co/absa/springdocopenapiscala/examples/simple/Application.scala renamed to examples/springdoc-openapi-scala-1/simple/src/main/scala/za/co/absa/springdocopenapiscala/examples/simple/Application.scala

@@ -30,7 +30,7 @@ class OpenAPIConfiguration {
     Seq((openAPI: OpenAPI) =>
       openAPI.setInfo(
         new Info()
-          .title("Example API")
+          .title("Example API with springdoc-openapi v1.x")
           .version("1.0.0")
       )
     )