Skip to content

Swagger/OpenAPI annotations V3 – use Enum values in swagger annotations

I’m creating the the API description of our application using Swagger/OpenApi V3 annotations, imported from following dependency:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.45</version>
</dependency>

One of the annotations is a @Schema annotation that accepts an attribute named allowableValues which allows a an array of strings:

@Schema(description = "example", 
        allowableValues = {"exampleV1", "exampleV2"}, 
        example = "exampleV1", required = true)
private String example;

Now I would like to use a custom method constructed on our Enum class that returns the allowable strings array, so it does not needs to be added upon each time we add a type to our Enum. So that we can use it like this:

public enum ExampleEnum {
    EXAMPLEV1, EXAMPLEV2;
    public static String[] getValues() {...}
}

@Schema(description = "example", 
        allowableValues = ExampleEnum.getValues(), 
        example = "exampleV1", required = true)
private String example;

Now this doesn’t compile because the method is not known when executing the annotation. Is there such a solution that allows usage of Enums in the swagger V3 annotation attributes values?

Had a look in following resources:

You can define reusable enums in the global components section and reference them via $ref elsewhere.

Worst case I can indeed have it defined in one constant place and after adding a type to the Enum only have one other place needed to add the type to. But I first want to explore the above mentioned solution if it’s possible.

Doesn’t say anything about using any classes or dynamic generated values.

Is about documenting enums in swagger and not using them in the swagger annotations API.

Answer

try using @Schema(implementation = ExampleEnum.class, ...), you can add all other properties you want. I would need more info on your implementation but try this first.