Array of enums ignores enum's schema description when rendered

[flaksp]

Example array schema:

{
  "description": "Роли пользователя.",
  "items": {
    "description": "Роль пользователя.\n\n* `ROLE_DEVELOPER`. Разработчик (имеет все возможные права).\n* `ROLE_MANAGER`. Менеджер (на данный момент является синонимом слова \"админ\").\n* `ROLE_MEDICAL_REPRESENTATIVE`. Медицинский представитель.",
    "example": "ROLE_DEVELOPER",
    "title": "Role",
    "type": "string",
    "nullable": false,
    "readOnly": false,
    "writeOnly": false,
    "enum": [
      "ROLE_DEVELOPER",
      "ROLE_MANAGER",
      "ROLE_MEDICAL_REPRESENTATIVE"
    ]
  },
  "maxItems": 3,
  "minItems": 0,
  "uniqueItems": true,
  "type": "array",
  "nullable": false
}

That's how ReDoc renders it in response section:

That's how ReDoc renders it in parameters section:

As you may see, ReDoc ignores description of enum schema. I didn't tested how ReDoc renders it in request section, but I'm sure result will be the same as in response section.

[RomanHotsiy]

Do you have any ideas of how to render it? I'm not sure what's the best behavior here.. Just append items description bellow array description?

[flaksp]

@RomanGotsiy, yes, appending below seems like a good idea.

Here's some example how I see it:

Or maybe it's better to indent it a bit:

Note that I have removed line "Items Enum".

[hleb-albau]

Also, we can generate description from popular extension x-enum-descriptions

[ernestomi]

Also, can we get rid of the word "Enum:" the actual name of the property in OAS (enum) bares no meaning to the end user of the API Docs. You could name it "Options" which is the word mentioned in the Open API Specification section 4.8.6.1