Swagger @Schema tag doesn't allow more than one example per type

[jonathanl-telenav]

In the code below, Swagger uses the second example for the first field as well. It would be nice if the example for startTime could be different than the example for endTime. -- Jon

    @JsonProperty
    @Schema(description = "The local start time and date to query",
            example = "2021.01.01-12.00am")
    @KivaKitIncludeProperty
    private LocalTime startTime;

    @JsonProperty
    @Schema(description = "The local end time and date to query",
            example = "2021.09.01-12.00am")
    @KivaKitIncludeProperty
    private LocalTime endTime;

[finsterwalder]

It's not just the examples that are used for all fields. Also the descriptions are used for all fields. This is the case, because the generated OpenAPI file contains a $ref to the one description for this type. So there is only one definition for this type in the generate OpenAPI file and as such it can only have one description/examples/... Instead in addition the the $ref other attributes should be written to the location, were the $ref is used, I think.

[finsterwalder]

After some more research I found, that OpenAPI actually defines:

Any sibling elements of a $ref are ignored. This is because $ref works by replacing itself and everything on its level with the definition it is pointing at.

So this could only be resolved by not referencing the one definition for the type, but by creating a new entry every time.

[jonathanl-telenav]

Hi @finsterwalder, I eventually came to the same conclusion. It seems like a flaw in the spec to be constantly repeating object definitions like that, but it does work.

[vanDarg]

Hi @finsterwalder, I eventually came to the same conclusion. It seems like a flaw in the spec to be constantly repeating object definitions like that, but it does work.

Excuse me if this goes too far off-topic, but how would you go about creating separate object definitions in this case? I am facing a similiar issue and would like to give different descriptions to fields of the same (custom) type.

[finsterwalder]

@vanDarg I created my own Annotation @NoRefSchema, and my own processing, that creates an inline type description in the OpenAPI yaml file.

[vanDarg]

Thanks for the reply! Not sure I can replicate that, especially since we are using springdoc-openapi to generate our documentation.

[finsterwalder]

That's exactly what we do. It's a little tricky, but we implemented an org.springdoc.core.customizers.PropertyCustomizer

[vanDarg]

Oh, that sounds great! I don't suppose you have an example lying around, do you? :-D

[finsterwalder]

Unfortunately I don't have anything that I can give you and your solution is working for us, but it's not really universal.

It basically starts with:

@Configuration public class MyPropertyCustomizer implements PropertyCustomizer {

private final OpenAPI openAPI; // can be autowired from Spring

@Override
public Schema customize(Schema property, AnnotatedType type) {
    if (property != null && type != null && type.getCtxAnnotations() != null) {
        for (Annotation annotation : type.getCtxAnnotations()) {
            final Class<? extends Annotation> annotationType = annotation.annotationType();

When the annotationType is your own Annotation: @NoRefSchema for example, you can create a new schema with:

       final Type annotatedType = type.getType();
        if (annotatedType instanceof JavaType) {
            JavaType javaType = (JavaType) annotatedType;
            final Class<?> rawClass = javaType.getRawClass();
            final String $ref = rawClass.getSimpleName() + "_" + REF_ID.incrementAndGet();
            final Schema newSchema = getSchema(rawClass);
            openAPI.schema($ref, newSchema);
            schema.$ref($ref);

where:

private Schema getSchema(Class aClass) {
    return ModelConverters.getInstance()
            .resolveAsResolvedSchema(new AnnotatedType(aClass).resolveAsRef(false))
            .schema;
}

That might get you started...

[vanDarg]

Thanks alot! I will definitely have a look at that.