swagger-api / swagger-api/swagger-ui

Standalone UI: Available values for discriminated union of enumerations in request body

Open
#9,178 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • OS: [e.g. Windows 10]
  • Browser: [chromium edge]
  • Version: [116.0.1938.62]
  • Method of installation: [NuGet with AspNetCore 6.0]
  • Swagger-UI version: [4.5.15]
  • Swagger/OpenAPI version: [OpenAPI 3.0.1]
Content & configuration

Swagger/OpenAPI definition:

openapi: 3.0.1
info:
  title: Sample
  version: '1.1'
paths:
  '/toggles/{name}':
    put:
      operationId: ChangeToggle
      parameters:
        - name: name
          in: path
          required: true
          schema:
            enum:
              - A
              - B
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
              oneOf:
                - $ref: '#/components/schemas/AValues'
                - $ref: '#/components/schemas/BValues'
              discriminator:
                propertyName: name
                mapping:
                  A: '#/components/schemas/AValues'
                  B: '#/components/schemas/BValues'
        required: true
      responses:
        '200':
          description: Success
components:
  schemas:
    AValues:
      enum:
        - A1
        - A2
      type: string
    BValues:
      enum:
        - B1
        - B2
      type: string
Screenshots

image

image

How can we help?

For the name parameter Swagger-UI shows handy dropdown and lists available values.
However for the requestBody parameter there is no equivalent UX. In addition, the only place were request body is related to oneOf element is in "Schema" tab which is not really user friendly.

I suggest to implement support for oneOf between enumerated schemas such that request body example value

  1. Is presented as a dropdown with values currently valid for the current selection of the name parameter
  2. There is similar comment, Available values

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

Reproduce the standalone UI with the supplied OpenAPI 3.0.1 definition and inspect the requestBody example controls alongside the Schema tab. Trace how the name parameter selection and oneOf enumerated schemas are rendered; done means the request body offers only the currently valid enum values and includes an Available values comment.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.