Auto display of list of enums in spring auto rest docs isn't explanatory

Question

I've generated a document using spring auto rest docs. This uses capital.scalable libraries combined with java docs and spring rest docs. My issue is with the List of enums while describing the request fields. Type column generates a value as Array[Object]. Also, the description column doesn't generate the must be one of statement with the enum values, as it does when only Enum is the field and not the list of enums.

public enum Discipline {
  ECONOMICS("economics"),
  SOCIOLOGYANTHROPOLOGY("sociologyanthropology");

  private final String discipline;

  Discipline(final String discipline) {
    this.discipline = discipline;
  }

  public String getId() {
    return discipline;
  }
}

Above is the enum that I have. It uses tostring correctly to display in the description when the field is used only as enum. But if list of enums i.e.

List<Discipline>

is the field, then it doesn't describe properly as mentioned above.

Please let me know what should be done to generate the document more effectively?

Answer 1

You are right that lists of enums are not properly supported yet.

If you have a request/response like:

class SomeRequest {

    public enum EnumTest {
        ONE, TWO
    }

    /**
     * List of enums
     */
    private List<EnumTest> enumTestList;
}

it is documented as with Spring Auto REST Docs at the moment.

It would be good if the type would be Array[String] and the description would list the elements of the enum, e.g. "Elements must be one of [...]".

Spring Auto REST Docs 1.0.11 fixes the type issue and thus Array[String] will be shown with this version.

I opened an issue to improve the documentation of lists of enums: https://github.com/ScaCap/spring-auto-restdocs/issues/194. Until this issue is resolved, one can manually add "Elements must be one of [...]" to the Javadoc of the list as a workaround.