Added the option to add OpenAPIDocsOptions to verifyClient/verifyServer (#5093)

Added the ability to include `OpenAPIDocsOptions` for `verifyClient` and
`verifyServer`

At $work we compare our service endpoint to the last production deployed
yaml to find inconsistencies. We recently wanted to try
`markOptionsAsNullable` but encountered issues - the resulting yaml
fails when compared to the endpoints.

The error we experienced is similar to what happens in `verifyServer -
respect OpenAPIDocsOptions` if you don't include custom
`OpenAPIDocsOptions`.

```scala
List(incompatible path /users:
- incompatible operation get:
  - incompatible response:
    - incompatible content:
      - incompatible media type application/json:
        - incompatible schema:
          List(incompatible anyOf/oneOf variant at index 1:
          - target schema is restricted to type object, type null is incompatible with it)) was not empty
ScalaTestFailureLocation: sttp.tapir.docs.openapi.OpenApiVerifierTest at (OpenApiVerifierTest.scala:138)
```

This PR solves this by allowing users to provide your
`OpenApiDocsOptions` to `OpenApiVerifier` so that they are more similar.

Author: felix-hedenstrom

docs/openapi-verifier/src/main/scala/sttp/tapir/docs/openapi/OpenAPIVerifier.scala

@@ -25,8 +25,12 @@ object OpenAPIVerifier {
     *   a list of `OpenAPICompatibilityIssue` instances detailing the compatibility issues found during verification, or `Nil` if no issues
     *   were found.
     */
-  def verifyClient(clientEndpoints: List[AnyEndpoint], serverSpecificationYaml: String): List[OpenAPICompatibilityIssue] = {
-    val clientOpenAPI = OpenAPIDocsInterpreter().toOpenAPI(clientEndpoints, "OpenAPIVerifier", "1.0")
+  def verifyClient(
+      clientEndpoints: List[AnyEndpoint],
+      serverSpecificationYaml: String,
+      docsOptions: OpenAPIDocsOptions = OpenAPIDocsOptions.default
+  ): List[OpenAPICompatibilityIssue] = {
+    val clientOpenAPI = OpenAPIDocsInterpreter(docsOptions).toOpenAPI(clientEndpoints, "OpenAPIVerifier", "1.0")
     val serverOpenAPI = readOpenAPIFromString(serverSpecificationYaml)
 
     OpenAPIComparator(clientOpenAPI, serverOpenAPI).compare()
@@ -42,8 +46,12 @@ object OpenAPIVerifier {
     *   a list of `OpenAPICompatibilityIssue` instances detailing the compatibility issues found during verification, or `Nil` if no issues
     *   were found.
     */
-  def verifyServer(serverEndpoints: List[AnyEndpoint], clientSpecificationYaml: String): List[OpenAPICompatibilityIssue] = {
-    val serverOpenAPI = OpenAPIDocsInterpreter().toOpenAPI(serverEndpoints, "OpenAPIVerifier", "1.0")
+  def verifyServer(
+      serverEndpoints: List[AnyEndpoint],
+      clientSpecificationYaml: String,
+      docsOptions: OpenAPIDocsOptions = OpenAPIDocsOptions.default
+  ): List[OpenAPICompatibilityIssue] = {
+    val serverOpenAPI = OpenAPIDocsInterpreter(docsOptions).toOpenAPI(serverEndpoints, "OpenAPIVerifier", "1.0")
     val clientOpenAPI = readOpenAPIFromString(clientSpecificationYaml)
 
     OpenAPIComparator(clientOpenAPI, serverOpenAPI).compare()

docs/openapi-verifier/src/test/scala/sttp/tapir/docs/openapi/OpenApiVerifierTest.scala

@@ -3,6 +3,8 @@ package sttp.tapir.docs.openapi
 import org.scalatest.funsuite.AnyFunSuite
 import sttp.tapir._
 import sttp.tapir.json.circe.jsonBody
+import io.circe.generic.auto._
+import sttp.tapir.generic.auto._
 
 class OpenApiVerifierTest extends AnyFunSuite {
   val openAPISpecification: String =
@@ -45,6 +47,50 @@ class OpenApiVerifierTest extends AnyFunSuite {
       |                type: string
       """.stripMargin
 
+  val openAPISpecificationMarkOptionAsNullable: String =
+    """openapi: 3.0.0
+      |info:
+      |  title: Sample API
+      |  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
+      |  version: 0.1.9
+      |
+      |servers:
+      |  - url: http://api.example.com/v1
+      |    description: Optional server description, e.g. Main (production) server
+      |  - url: http://staging-api.example.com
+      |    description: Optional server description, e.g. Internal staging server for testing
+      |
+      |paths:
+      |  /users:
+      |    get:
+      |      summary: Returns a list of users.
+      |      description: Optional extended description in CommonMark or HTML.
+      |      responses:
+      |        "200": # status code
+      |          description: A JSON array of user names
+      |          content:
+      |            application/json:
+      |              schema:
+      |                anyOf:
+      |                - $ref: '#/components/schemas/FullName'
+      |                - type: 'null'
+      |components:
+      |  schemas:
+      |    FullName:
+      |      title: FullName
+      |      type: object
+      |      required:
+      |      - firstName
+      |      - lastName
+      |      properties:
+      |        firstName:
+      |          type: string
+      |        lastName:
+      |          type: string
+      |      """.stripMargin
+
+  case class FullName(firstName: String, lastName: String)
+
   test("verifyServer - all client openapi endpoints have corresponding server endpoints") {
     val serverEndpoints = List(
       endpoint.get
@@ -84,6 +130,24 @@ class OpenApiVerifierTest extends AnyFunSuite {
     assert(OpenAPIVerifier.verifyServer(serverEndpoints, openAPISpecification).nonEmpty)
   }
 
+  test("verifyServer - respect OpenAPIDocsOptions") {
+    val serverEndpoints = List(
+      endpoint.get
+        .in("users")
+        .out(jsonBody[Option[FullName]])
+    )
+
+    assert(
+      OpenAPIVerifier
+        .verifyServer(
+          serverEndpoints,
+          openAPISpecificationMarkOptionAsNullable,
+          OpenAPIDocsOptions.default.copy(markOptionsAsNullable = true)
+        )
+        .isEmpty
+    )
+  }
+
   test("verifyClient - all server openapi endpoints have corresponding client endpoints") {
     val clientEndpoints = List(
       endpoint.get
@@ -122,4 +186,22 @@ class OpenApiVerifierTest extends AnyFunSuite {
 
     assert(OpenAPIVerifier.verifyClient(clientEndpoints, openAPISpecification).isEmpty)
   }
+
+  test("verifyClient - respect OpenAPIDocsOptions") {
+    val clientEndpoints = List(
+      endpoint.get
+        .in("users")
+        .out(jsonBody[Option[FullName]])
+    )
+
+    assert(
+      OpenAPIVerifier
+        .verifyClient(
+          clientEndpoints,
+          openAPISpecificationMarkOptionAsNullable,
+          OpenAPIDocsOptions.default.copy(markOptionsAsNullable = true)
+        )
+        .isEmpty
+    )
+  }
 }