added comment about usage of anyOf for nullable schemas

softwaremill · Apr 17, 2024 · bac9578 · bac9578
1 parent bc448d7
commit bac9578
Showing 1 changed file with 3 additions and 0 deletions.
diff --git a/apispec-model/src/main/scala/sttp/apispec/Schema.scala b/apispec-model/src/main/scala/sttp/apispec/Schema.scala
@@ -136,6 +136,9 @@ case class Schema(
  else copy(`type` = Some(types :+ SchemaType.Null))
 
  case None =>
+ // Representing nullable schemas (without explicit `type`) using `anyOf` is safer than `oneOf`.
+ // If `oneOf` was used, and the original schema was already nullable, `null` would not be a valid
+ // value for the resulting schema.
  val nullSchema = Schema(SchemaType.Null)
  if(anyOf.contains(nullSchema)) this // ensure idempotency
  else if (anyOf.nonEmpty) copy(anyOf = anyOf :+ nullSchema)