Redocly / Redocly/redoc

showExtension option on array of strings does not show extensions

Open
#2,559 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the bug
In an openapi spec, using the x-extensible-enum extension and the showAnnotations option, the extension is not rendered, when the type is an array of enum

Expected behavior
I expect the extensions to be shown, similar to what happens when an array of enum is rendered.

Minimal reproducible OpenAPI snippet(if possible)
Consider the following spec:

openapi: 3.1.0
info:
  title: Minimal Museum API
  version: 1.0.0
servers:
  - url: 'https://api.fake-museum-example.com/v1'
paths:
  /museum-hours:
    get:
      summary: Get museum hours
      operationId: getMuseumHours
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  hours:
                    type: array
                    items:
                      type: string
                      x-extensible-enum:
                        - OPEN
                        - CLOSED
                  hours2:
                    type: array
                    items:
                      type: string
                      enum:
                        - OPEN
                        - CLOSED

Screenshots

Bildschirmfoto 2024-07-15 um 16 22 08

Additional context

I know that x-extensible-enum is not supported directly, however I found that with the showExtensions option enabled, it works well enough for our use case. I do have a fix in mind, however I don't know if this would have any unwanted side effects that I can't think of. I will open a draft PR containing my fix and I would be happy if you would consider my change.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the minimal OpenAPI 3.1 snippet and compare rendering for the array using x-extensible-enum with the array using enum while showExtensions or showAnnotations is enabled. Trace the schema rendering path for array items and confirm that the extension values appear in the generated documentation without changing existing enum rendering.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.