Array with enum values in items: nested description not displayed

[AnnikaStrupp-initAG]

Describe the bug

The generated documentation does not display a 'description' text provided on the level of 'enum' in array 'items'.

Expected behavior

The 'description' is rendered and displayed on screen. This would be particularly useful for $ref referenced codelists in 'items' that come with their own description.

Current behavior

The generated documentation does not display a 'description' text provided on the level of 'enum' in array 'items'. The specified set of 'enum' values is correctly displayed as 'Possible values'.

Steps to reproduce

example-array .yaml

  example:
    type: array
    items:
      enum:
        - 1
        - 2
        - 3
        - string
      description: >
        This description is sadly not rendered.

Version used:

• node.js 20.12.1
• Docusaurus 3.4.0
• Docusaurus OpenAPI Docs 3.0.1
• Windows desktop

[sserrata]

Hi @AnnikaStrupp-initAG, thanks for opening this issue. Can you explain why it wouldn't make sense to define description at the same level as type? Also, can you help me find where in the official OpenAPI documentation this feature is defined/described? Thanks!

[aldafu]

why it wouldn't make sense to define description at the same level as type?

It makes sense and is really useful when you want define the items of the array in a OpenAPI ReferenceObject that you then can reference in multiple places without repeating yourself. And then obviously have the description property as part of that same ReferenceObject to describe the enum in detail.

Let me also add that rapidoc and openapi-explorer handle this case as expected, i.e. the description property is rendered and displayed.

can you help me find where in the official OpenAPI documentation this feature is defined/described? Thanks!

Sure thing, go here https://swagger.io/specification/v3/#schema-object and have a look at the second part under the "Properties" section where you will find type and description properties equally, i.e. same level.