3234: use markOptionsAsNullable for Option reference types

docs/apispec-docs/src/main/scala/sttp/tapir/docs/apispec/schema/TSchemaToASchema.scala

@@ -26,7 +26,12 @@ private[schema] class TSchemaToASchema(toSchemaReference: ToSchemaReference, mar
       case TSchemaType.SArray(nested @ TSchema(_, Some(name), _, _, _, _, _, _, _, _, _)) =>
         ASchema(SchemaType.Array).copy(items = Some(toSchemaReference.map(nested, name)))
       case TSchemaType.SArray(el) => ASchema(SchemaType.Array).copy(items = Some(apply(el)))
-      case TSchemaType.SOption(nested @ TSchema(_, Some(name), _, _, _, _, _, _, _, _, _)) => toSchemaReference.map(nested, name)
+      case TSchemaType.SOption(nested @ TSchema(_, Some(name), _, _, _, _, _, _, _, _, _)) => {
+        val ref = toSchemaReference.map(nested, name)
+        if (!markOptionsAsNullable) ref
+        else
+          ASchema.oneOf(List(ref), ref.discriminator).copy(nullable = Some(true))
+      }
       case TSchemaType.SOption(el)                                                         => apply(el, isOptionElement = true)
       case TSchemaType.SBinary()      => ASchema(SchemaType.String).copy(format = SchemaFormat.Binary)
       case TSchemaType.SDate()        => ASchema(SchemaType.String).copy(format = SchemaFormat.Date)

docs/openapi-docs/src/test/resources/expected_nullable_option_class_field.yml

@@ -0,0 +1,48 @@
+openapi: 3.1.0
+info:
+  title: ClassWithOptionClassField
+  version: '1.0'
+paths:
+  /:
+    post:
+      operationId: postRoot
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ClassWithOptionClassField'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            text/plain:
+              schema:
+                type: string
+        '400':
+          description: 'Invalid value for: body'
+          content:
+            text/plain:
+              schema:
+                type: string
+components:
+  schemas:
+    Bar:
+      required:
+        - bar
+      type: object
+      properties:
+        bar:
+          type: integer
+          format: int32
+    ClassWithOptionClassField:
+      required:
+        - requiredStringField
+      type: object
+      properties:
+        optionalClassField:
+          oneOf:
+            - $ref: '#/components/schemas/Bar'
+            - type: 'null'
+        requiredStringField:
+          type: string

docs/openapi-docs/src/test/scalajvm/sttp/tapir/docs/openapi/VerifyYamlTest.scala

@@ -666,6 +666,20 @@ class VerifyYamlTest extends AnyFunSuite with Matchers {
     actualYamlNoIndent shouldBe expectedYaml
   }
 
+  test("should mark optional class fields as nullable when configured to do so") {
+    case class Bar(bar: Int)
+    case class ClassWithOptionClassField(optionalObjField: Option[Bar], requiredStringField: String)
+
+    val e = endpoint.in(jsonBody[ClassWithOptionClassField]).out(stringBody).post
+    val expectedYaml = load("expected_nullable_option_class_field.yml")
+
+    val options = OpenAPIDocsOptions.default.copy(markOptionsAsNullable = true)
+
+    val actualYaml = OpenAPIDocsInterpreter(options).toOpenAPI(e, Info("ClassWithOptionClassField", "1.0")).toYaml
+    val actualYamlNoIndent = noIndentation(actualYaml)
+    actualYamlNoIndent shouldBe expectedYaml
+  }
+
   test("should generate default and example values for nested optional fields") {
     case class Nested(nestedValue: String)
     case class ClassWithNestedOptionalField(