Document 'x-enum-descriptions' and 'x-enum-varnames'

[jmini]

PR checklist

• Read the contribution guidelines.
• Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh and ./bin/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\.
• Filed the PR against the correct branch: master, 3.4.x, 4.0.x. Default: master.
• Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

Fixes #1871

[jimschubert]

@jmini this looks good. Are there any special cases to consider? For example, if enum values aren't in sorted order:

enum:
  - 7
  - 4
  - 1

Is the user to assume the names and descriptions follow the documented order?

[jmini]

@jimschubert:

enum, x-enum-descriptions and x-enum-varnames are each expected to be list of items. They are sorted. First items of each list are grouped together ("1", "Blue sky" and "Sunny" in the example), second items and so on... In the ideal case, the list have the same amount of items but we handle cases where it is not the case.

[jimschubert]

@jmini Thanks for the update. I think this is very clear. I've approved the PR, but for some reason it shows the builds as red.

I'm traveling today, so I won't be able to keep an eye on the build after a merge. Feel free to merge.

[yosev]

Looks like type: boolean is trying to instantiate an enum with a string as parameter instead of boolean when generating java spring

UserAccess:
      type: boolean
      enum:
        - true
        - false
        - true
      x-enum-descriptions:
        - "Blue sky"
        - "Slightly overcast"
        - "Take an umbrella with you"
      x-enum-varnames:
        - Sunny
        - Cloudy
        - Rainy

public enum UserAccess {
  
  Sunny("true"),
  
  Cloudy("false"),
  
  Rainy("true");

  private Boolean value;

  UserAccess(Boolean value) {
    this.value = value;
  }

  @Override
  @JsonValue
  public String toString() {
    return String.valueOf(value);
  }

  @JsonCreator
  public static UserAccess fromValue(String text) {
    for (UserAccess b : UserAccess.values()) {
      if (String.valueOf(b.value).equals(text)) {
        return b;
      }
    }
    throw new IllegalArgumentException("Unexpected value '" + text + "'");
  }
}