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).

The 1.x branch of this project will only work with Springfox 2.x.

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

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

@Configuration
@Import(ApiEnumDescriptionPlugin.class) // add this line
public void MySpringConfiguration {
	...
}

The plugin automatically registers with Springfox (version 2) and will process these proprietary @ApiEnum annotations:

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

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

@ApiModelProperty("Some description.")
SomeEnum attribute;

@ApiModelProperty(value = "Some description.", dataType = "...SomeEnum")
Integer attribute2;

public void someMethod(@ApiParam("Some description.") SomeEnum param) { ... }

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_

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

public enum SomeEnumWithJsonValueAnnotation {
    @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.
     */
    public String toJson() {
        return name().toLowerCase().replace('_', '-');
    }
}

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.