✏️ springfox-enum-plugin

OpenAPI / Swagger / Springfox provide no way of documenting enumerations in a structured way (as of OpenAPI 3.0). This Springfox plugin introduces the @ApiEnum annotation to automate the current suggestion: "If you need to specify descriptions for enum items, you can do this in the description of the parameter or property" (swagger.io).

Compatibility with Springfox

Springfox 2.x <-> springfox-enum-plugin 1.x.

Springfox 3.x <-> springfox-enum-plugin 3.x.

Maven Coordinates

<!-- https://mvnrepository.com/artifact/de.pentabyte/springfox-enum-plugin -->
<dependency>
<groupId>de.pentabyte</groupId>
<artifactId>springfox-enum-plugin</artifactId>
<version>3.0.0</version>
</dependency>

Usage

Make your Spring application use this component: ApiEnumDescriptionPlugin. Example:

@Configuration@Import(ApiEnumDescriptionPlugin.class) // add this linepublicvoidMySpringConfiguration {
...
}

The plugin automatically registers with Springfox and will process these proprietary @ApiEnum annotations:

publicenumSomeEnum {
/** * Java Doc comment */@ApiEnum("First Option")
A, //@ApiEnum("Second Option")
B, //C
}

Then - whenever such an enumeration is used in combination with @ApiModelProperty property or @ApiParam, the plugin will extend the standard description. Examples:

@Getter@Setter
...
@ApiModelProperty("Some description.")
SomeEnumattribute;
@ApiModelProperty(value = "Some description.", dataType = "org.example.SomeEnum")
Integerattribute2;
publicvoidsomeMethod(@ApiParam("Some description.") SomeEnumparam) { ... }

It effectively produces this description in markdown syntax for attribute, attribute2 and param. It will not touch the description if none of the enums are annotated, though.

Some description.
* A: First option
* B: Second option
* C: _@ApiEnum annotation not available_

Custom Enum Names

The plugin will also pick up Jackson's custom mapping of enum names like this one:

publicenumSomeEnumWithJsonValueAnnotation {
@ApiEnum("A One")
A_1, //@ApiEnum("B Two")
B_2;
@com.fasterxml.jackson.annotation.JsonValue/** * A_1 and B_2 will be mapped to a-1 and b-2. */publicStringtoJson() {
returnname().toLowerCase().replace('_', '-');
}
}

Outlook

It seems obvious that this a temporary solution. Once the OpenAPI specs provide a relevant new feature for handling enumerations, it should be fairly simple to drop the usage of this plugin and replace all @ApiEnum annotations with their future counterparts.