13

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.

ℛɑƒæĿᴿᴹᴿ
  • 4,983
  • 4
  • 38
  • 58
bramdc
  • 580
  • 1
  • 5
  • 21

2 Answers2

9

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.

Tarnished-Coder
  • 318
  • 2
  • 7
  • Unfortunately I don't have the code anymore so I cannot try it out anymore... Anybody else can confirm this? – bramdc May 23 '20 at 10:38
  • this does not seem to work for me as I add @Schema(implementation = MyEnum.class) to one of the parameters in a controller. – ojathelonius Jan 22 '21 at 14:40
  • @ojathelonius Please share your code and more context for your issue – Tarnished-Coder Jan 27 '21 at 19:29
  • 3
    I confirm it works well, at least on **OpenAPI v2**, just verified in several places of my code and this helped me a lot! Thanks! – RAM237 Feb 14 '21 at 14:32
  • 1
    For anybody trying to get this working with an array: use @ArraySchema(schema = @Schema(implementation = ExampleEnum.class)) instead! – Snackaholic Jan 11 '22 at 11:25
5

In my case, I have added an annotation in my enum:

@Schema(enumAsRef = true)
public enum WikipediaLanguage {
  ...
}

and then just used it annotated as a Parameter in the argument of they REST controller method:

@Parameter(
    description = "Language of the Wikipedia in use",
    required = true
) @RequestParam WikipediaLanguage lang
Benjamín Valero
  • 159
  • 1
  • 5