Allow documenting individual enum values using Javadoc

[NikolasFunction]

Is your feature request related to a problem? Please describe.

Currently, it is not possible to document each individual value of an enum using Springdoc-OpenAPI using pure Javadoc documentation without relying on annotations. While it is possible to document the parameter using the @Parameter annotation with descriptions for each value (example: @Parameter(description = "Sort order:\n * `asc` - Ascending, from A to Z\n * `desc` - Descending, from Z to A")), it has a lot of disadvantages, such as being verbose and potentially leading to inconsistent documentation across different endpoints.

The resulting Swagger UI should be like this:

Describe the solution you'd like

I would like to be able to document each individual value of an enum using Javadoc documentation in Springdoc-OpenAPI, without relying on annotations. This would allow for more concise and consistent documentation across different endpoints, and make it easier for users to understand the available options and their meanings.

For example, I would like to be able to document a @GetMapping method using Javadoc documentation, such as:

/**
 * ...
 * @param sortingEnum Sort order.
 * @return ...
 */
@GetMapping("/items")
public List<Item> getItems(@RequestParam(value = "sort-order", defaultValue = "asc") SortingEnum sortingEnum) {
    // Implementation
}

And document the enum using Javadoc documentation, such as:

/**
 * ...
 * /
enum SortingEnum {
    /**
     * Ascending, from A to Z.
     */
    asc,

    /**
     * Descending, from Z to A.
     */
    desc
}

Describe alternatives you've considered

Stated above.

Additional context

If this feature could be implemented, it would be a great addition to the Springdoc-OpenAPI library and would make it easier for developers to create high-quality API documentation.

Follow this link to see how OAS3 handles enum descriptions: https://swagger.io/docs/specification/data-models/enums/

[esotericman]

You can add a field for your Enum description ,and then override toString method. see there override toString on your enum

[NikolasFunction]

Based on my understanding, it seems that your suggestion concerns only the base information of enums. This includes a description of the field (parameter) itself and the available values. In Java/Spring this information can be automatically generated. The available values are determined by springdoc (in my case my enum method getJsonIdentifier() is annotated with @JsonValue). The general enum description is determined by springdoc-javadoc (by simply documenting the java method's parameter).

However, what your suggestion lacks is a detailed description/documentation of each enum value, as mentioned earlier.

[bnasslahsen]

@NikolasFunction,

This is an enhancement nice to have but we will not invest on it. Feel free to propose a PR, if you believe it's useful for the community and we will be happy to review it.