SpringDocSealedClassModule overrides Schema annotations

[Mattias-Sehlstedt]

The added SpringDocSealedClassModule in the release of version 2.8.5 has made it so that any sealed api-class will have any current polymorphic @Schema annotation override by the module's introspection.

I am wondering if it is intended behavior that the module should always take control of the schema? Or is a better behavior to have the module as a fallback schema provider if the model does not already have an explicit schema defined? I have an example branch here showing how an annotation could look like and what the previous schema generation resulted in. It is the same example as the one shown below in this issue.

TL;DR: would it be logical to introduced so that the module only creates a schema if there is a lack of a @Schema annotation with a OneOf.

An example of a definition could be:

@Schema(name = SuperClass.SCHEMA_NAME,
        discriminatorProperty = "type",
        oneOf = {
                FirstChildClass.class,
                SecondChildClass.class
        },
        discriminatorMapping = {
                @DiscriminatorMapping(value = FirstChildClass.SCHEMA_NAME, schema = FirstChildClass.class),
                @DiscriminatorMapping(value = SecondChildClass.SCHEMA_NAME, schema = SecondChildClass.class)
        }
)
sealed class SuperClass permits FirstChildClass, SecondChildClass {
...
}

Where the schema earlier would be:

{
  "schemas": {
    "Image": {
      "required": [
        "type"
      ],
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        }
      }
    },
    "Mail": {
      "required": [
        "type"
      ],
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        }
      }
    },
    "SuperClass": {
      "required": [
        "type"
      ],
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        }
      },
      "discriminator": {
        "propertyName": "type",
        "mapping": {
          "Image": "#/components/schemas/Image",
          "Mail": "#/components/schemas/Mail"
        }
      },
      "oneOf": [
        {
          "$ref": "#/components/schemas/Image"
        },
        {
          "$ref": "#/components/schemas/Mail"
        }
      ]
    }
  }
}

but now becomes:

{
  "schemas": {
    "Image": {
      "required": [
        "type"
      ],
      "type": "object",
      "allOf": [
        {
          "$ref": "#/components/schemas/SuperClass"
        }
      ]
    },
    "Mail": {
      "required": [
        "type"
      ],
      "type": "object",
      "allOf": [
        {
          "$ref": "#/components/schemas/SuperClass"
        }
      ]
    },
    "SuperClass": {
      "required": [
        "type"
      ],
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        }
      },
      "discriminator": {
        "propertyName": "type",
        "mapping": {
          "Image": "#/components/schemas/Image",
          "Mail": "#/components/schemas/Mail"
        }
      },
      "oneOf": [
        {
          "$ref": "#/components/schemas/Image"
        },
        {
          "$ref": "#/components/schemas/Mail"
        }
      ]
    }
  }
}

The issue with this is the recursive SuperClass oneOf Image -> Image allOf SuperClass -> SuperClass oneOf Image -> ....

I am aware that a solution is to disable this new module (by for example overriding the SpringDocProviders and not providing the new module).

But to me it would make more sense if the defined module is rather a fallback for the case when the model does not contain an explicit polymorphic schema annotation already. So I am wondering if such a feature would be accepted if I were to introduce that behavior in a PR (e.g., only attempt to construct a schema for the model if the current @Schema annotation does not contain a OneOf).