Provide documentation for RequiredMode

[spartanhooah]

I am updating a project from Swagger v2. I found that the required attribute of @Schema is deprecated, and requiredMode should be used instead. The default value of requiredMode is AUTO, but the javadocs don't explain what that means. Please update the documentation.

[sinclairjaza]

If the requiredMode parameter is set to AUTO, swagger will check upstream whether your field is marked with @NotBlank or @NotNull or ... to set the requiredMode to REQUIRED or NOT_REQUIRED otherwise.

For example :

public class Test{
    @JsonProperty("property")
    @Schema(description = "My property")
    private String property; //this field will be NOT_REQUIRED because it's not marked as @NotBlank or @NotNull or ...

    @NotBlank
    @JsonProperty("property_2")
    @Schema(description = "My property_2")
    private String property2; //this field is REQUIRED as it is marked as @NotBlank 
}

[jbauerrfid]

This is explained here: https://javadoc.io/static/io.swagger.core.v3/swagger-annotations/2.2.35/io/swagger/v3/oas/annotations/media/Schema.html#requiredMode()

Allows to specify the required mode (RequiredMode.AUTO, REQUIRED, NOT_REQUIRED) RequiredMode.AUTO: will let the library decide based on its heuristics.

Use the annotation like this:

    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    private String name;
    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    private String description;

[spartanhooah]

It's mentioned there in the documentations, yes, but "based on its heuristics" is not helpful to consumers.

[olijaun]

Am I supposed to try it or look at the source code to find out what it does? Swagger is a documentation tool and it should document itself properly. I agree that "based on heuristics" is not helpful at all. Please document.

Are fields declared as primitive datatype automatically required with this mode?

[olijaun]

@sinclairjaza You're explaining what happens when your properties are an object. What happens if your property is a primitive type (int, long, boolean, ...). What are the "heuristics"?

[daniel-kmiecik]

@spartanhooah Thank you for pointing this out. I created a PR for this #4982
It will be released with the next version.