support nullable ref in openapi schema

[cornerman]

I was missing support for nullable refs in the openapi schema. That is usually some optional case classes in the json schema.

It is inspired by this stack overflow response: https://stackoverflow.com/a/48114924
See also: OAI/OpenAPI-Specification#1368

Related: #1147

[kciesielski]

@cornerman Thanks for this proposition! I have just added an utility for convenient conversion between Tapir schemas and JSON schemas. It uses TSchemaToASchema underneath and I tried your change with it. It seems that the check you've implemented won't actually be applied to optional case class fields.
Could you add a test? For example in TapirSchemaToJsonSchemaTest.scala (please make sure you have the latest master).
Something simple like

    // given
    case class Parent(innerChildField: Option[Child])
    case class Child(childId: String)
    val tSchema = implicitly[Schema[Parent]]

    // when
    val result: ASchema = TapirSchemaToJsonSchema(tSchema, markOptionsAsNullable = true).value

    // then
    result.asJson.deepDropNullValues shouldBe json"""{}""" // expected json goes here

  }

The problem may be caused by nullable never being true, because pattern matching actually falls into this case:

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

Line 29 in a543d58

case TSchemaType.SOption(nested @ TSchema(_, Some(name), _, _, _, _, _, _, _, _, _)) =>

[cornerman]

This is related to #3331.

Closing this PR, because the code base has changed and the proposed change here did not really work.