Utilizing Enum Values in Swagger Annotations for Swagger/OpenAPI Annotations V3

One possible solution is to add an annotation to the currency field, which will prompt the plugin to skip generating properties. However, it remains unclear if it is possible to use Enums in the swagger V3 annotation attributes values. Some resources have been consulted, such as the one available at https://swagger.io/docs/specification/data-models/enums/. If necessary, a fallback option is to define the Enum type in one constant place, and then add it to another place when adding a new type to the Enum.


Question:

I am utilizing Swagger/OpenApi V3 annotations, which are imported from a dependency, to formulate the API description for our application.


    org.springdoc
    springdoc-openapi-ui
    1.1.45

There is an annotation referred to as

@Schema

that has an attribute called

allowableValues

. This attribute permits an array of strings to be accepted.

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

I wish to utilize a personalized technique established on our Enum category that presents the authorized string array. This method would prevent the need to add it every time we append a new type to our Enum. Consequently, we can refer to it in this manner:

public enum ExampleEnum {
    EXAMPLEV1, EXAMPLEV2;
    public static String[] getValues() {...}
}
@Schema(description = "example", 
        allowableValues = ExampleEnum.getValues(), 
        example = "exampleV1", required = true)
private String example;

The reason for the compilation failure is that the annotation does not recognize the method during execution. Is there a way to utilize Enums in the attribute values of Swagger V3 annotations?

Had a look in following resources:

  • The website mentioned provides information about enums in the Swagger specification for data models.

In the global components section, you have the option to define reusable enums. These enums can then be referenced via $ref in other parts of the code.

In the worst scenario, defining it in a single constant location and adding the type to the Enum in just one other place may suffice. However, before considering this option, I would like to investigate the aforementioned solution’s feasibility.

  • Check out the Swagger-2.X-Annotations wiki page on the Swagger-API GitHub repository for information about schemas.

There is no mention of utilizing classes or values that are generated dynamically.

  • Enum in swagger

The topic at hand pertains to the inclusion of enums in Swagger documentation, without utilizing them within the
swagger annotations
API.


Solution 1:

Utilize the

@Schema(implementation = ExampleEnum.class, ...)

and incorporate any other desired attributes. However, additional details on your execution are required. It’s recommended to try this approach initially.


Solution 2:


I have included an annotation in my enum, as it pertains to my situation.

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

Afterwards, the Parameter was simply annotated and utilized in the argument of the
REST controller
method.

@Parameter(
    description = "Language of the Wikipedia in use",
    required = true
) @RequestParam WikipediaLanguage lang

Frequently Asked Questions