How to use @Schema with Properties for OAS? No examples, which annotation to use?

[antonalechnovic]

How to represent properties in the link below?

https://swagger.io/docs/specification/data-models/data-types/#object

I am looking through openspec java annotations , nothing to help with properties, totally lost, what I am supposed to do here?

responses = {@ApiResponse( description = "Accepted", content = @Content(mediaType = "application/json", schema = @Schema(type = "object", properties = THIS_PROPERTIES_PROPERTY_IS_MISSING )))}

[antonalechnovic]

there is a class ref as param everywhere , but as soon as I put my Response class it just adds component ref, how is this supposed to work? The response in question is very simple and contains single property, I don't want reusable component for a response type used single time.

[agustisanchez]

With the Schema class, it is possible to define nested properties this way:

        new Schema().type("object")
                .addProperties("prop1",
                        new Schema().type("string"))
                .addProperties("prop2", 
                        new Schema().type("boolean"));

Apparently there's no way to achieve the same with the related @Schema annotation which forces to define classes only to generate documentation, which is not a good practice.

We need to be able to define (nested) properties in @Schema annotation, too.

[antonalechnovic]

With the Schema class, it is possible to define nested properties this way:

        new Schema().type("object")
                .addProperties("prop1",
                        new Schema().type("string"))
                .addProperties("prop2", 
                        new Schema().type("boolean"));

Apparently there's no way to achieve the same with the related @Schema annotation which forces to define classes only to generate documentation, which is not a good practice.

We need to be able to define (nested) properties in @Schema annotation, too.

This is becoming severe issue to stop using Swagger via java and spring openspec together, because there is no escape route for things which hard to represent with autogeneration.

How to use this raw code in @RestController ?

[rwe17]

I'm running into the same issue and just want to add documentation to properties of a request model class.
It seems impossible to add just a description to a property without generation a new superfluous schema. Is there really no solution for that common problem?

[frantuma]

#4129 introduces support to define Schema properties via annotations. Please see this and this examples for usage scenarios.