Redocly / Redocly/redoc

Response example name not displayed when "examples:" section only contains one item

Open
#2,192 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug
When an endpoint's response examples: section contains a single item, the name of that item doesn't appear above the JSON example code in the right content pane.

Expected behavior
When an endpoint's response examples: section contains a single item, the name of that item appears above the JSON example code in the right content pane -- either in a dropdown box (as when the examples: section contains multiple items), or in some other fashion (e.g. label/text).

Minimal reproducible OpenAPI snippet(if possible)

Open API snippet (response "examples:" contains one (1) item)
paths:
  '/sites/{siteId}/users/{userId}/cart/clear':
    post:
      tags:
        - CartApi
      summary: Delete all items in a cart.
      description: <p><i>No comparable method currently exists in the monolith's codebase; this is new functionality.</i></p><p>Delete all quantities & properties of all products & services that were previously added to a shopping cart.</p>
      operationId: CartApi_DeleteAllItemsInCart
      parameters:
        - name: siteId
          in: path
          description: ID of the site to which the shopping cart is scoped.
          required: true
          schema:
            maximum: 2147483647
            minimum: 1
            type: integer
            format: int32
        - name: userId
          in: path
          description: ID of the user to whom the shopping cart is scoped.
          required: true
          schema:
            maximum: 2147483647
            minimum: 1
            type: integer
            format: int32
      responses:
        '200':
          description: <p>The API request was successfully processed; an object describing the empty cart is returned.</p>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCartSummaryResponse'
              examples:
                All items in the shopping cart were deleted.:
                  value: {"cartGuid":"0fa1ef5f-5395-4679-901d-fd6c941f3460","cartItems":[]}
Open API snippet (response "examples:" contains two (2) items)
paths:
  '/sites/{siteId}/users/{userId}/cart/clear':
    post:
      tags:
        - CartApi
      summary: Delete all items in a cart.
      description: <p><i>No comparable method currently exists in the monolith's codebase; this is new functionality.</i></p><p>Delete all quantities & properties of all products & services that were previously added to a shopping cart.</p>
      operationId: CartApi_DeleteAllItemsInCart
      parameters:
        - name: siteId
          in: path
          description: ID of the site to which the shopping cart is scoped.
          required: true
          schema:
            maximum: 2147483647
            minimum: 1
            type: integer
            format: int32
        - name: userId
          in: path
          description: ID of the user to whom the shopping cart is scoped.
          required: true
          schema:
            maximum: 2147483647
            minimum: 1
            type: integer
            format: int32
      responses:
        '200':
          description: <p>The API request was successfully processed; an object describing the empty cart is returned.</p>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCartSummaryResponse'
              examples:
                All items in the shopping cart were deleted.:
                  value: {"cartGuid":"0fa1ef5f-5395-4679-901d-fd6c941f3460","cartItems":[]}
                DUMMY:
                  value: {"cartGuid":"0fa1ef5f-5395-4679-901d-fd6c941f3460","cartItems":[]}

Screenshots

Open API screenshot (response "examples:" contains one (1) item)

image

Open API screenshot (response "examples:" contains two (2) items)

image

Additional context
Add any other context about the problem here.

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

No source files or tests are named in the issue. Reproduce the behavior with the provided OpenAPI snippets, comparing a response with one example against one with two examples; done when the single example's name is displayed above the JSON example in the right content pane.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
documentation, frontend
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.