Yaml generation inconsistency

[morgado-ricardo]

Describe the bug

Me and some colleagues have recently started refactoring an old socket interface to REST using Spring Boot, with a code-first openAPI documentation approach that uses SpringDoc. We've got the API well annotated, and the client generation is working fine for the most part. The project is Java 8 and uses the gradle plugin to call the springdoc openapi generation.

We noticed that one particular Model class can have its output definition changed depending on which class is analyzed first to generate the YAML. This class is a regular enum (properly annotated with a @Schema) that is used in 2 separate locations in two other different model classes:

1. First we have a class, that defines a single object of our enum, with a @Schema annotation that has a description and a defaultValue;
2. Then, another class defines an ArrayList of our enum object, properly annotated with the @ArraySchema, providing schema = @Schema that holds an example of a valid value for this ArrayValue;

What we have noticed is that maybe this is in a way connected issue #857, but not in a sense of the output ordering, but that in our case, the resulting YAML really is different depending on which of the enum usages is analyzed first during the OpenAPI generation, and we don't seem to have any control over this. The Schema for our enum class sometimes has the "correct" default if the class in 1. is found first, and if 2. there is no default and it contains an example from the arraylist.

To illustrate the issue, I've created this simple repository, which despite being extremely small, was able to reproduce the problem and output different yaml files in the first times being ran (I've uploaded the first 5 files, and you can see the difference between yaml_1 and yaml_2).

To Reproduce

All the versions can be seen in the repository. To reproduce it, we just have to run gradlew generateOpenApiDocs multiple times, and look at the output build/openapi/inconsistencysample-api.yaml file.

Expected behavior

I would expect the yaml to be consistent across multiple runs, regardless on which class is analyzed first: The default value, which characterizes the specific object should appear on the yaml file, while the arraylist example doesn't belong there.

[bnasslahsen]

@ricardo-t-morgado,

You are sharing the same schema and you want here to have different descriptions for the same class.
You should instead declare two different schemas for your enum:

Here are some code samples:

• Ability to define different schemas for the same class #685
• @Parameter with the same class overrides description #782

[morgado-ricardo]

Thanks for the explanation and examples provided 👍