Support Conditional Field Visibility (Enum-Based & General If–Else Logic) in Swagger UI

Content & configuration

Swagger/OpenAPI definition:

# Example use case:
# A multipart/form-data request where certain fields should only
# appear based on another field’s value.
type: object

properties:

content_type:

type: string

enum: [HTML, FILE, INTERNAL_LINK, EXTERNAL_LINK]
content_value:

type: string

description: Only valid when content_type = HTML
file:

type: string

format: binary

description: Only valid when content_type = FILE
url:

type: string

description: Only valid when content_type = INTERNAL_LINK or EXTERNAL_LINK
is_advanced:

type: boolean

description: General conditional logic example
advanced_settings:

type: string

description: Shown only when is_advanced = true

Swagger-UI configuration options:

SwaggerUI({
  // No existing functionality for conditional field rendering
})

?yourQueryStringConfig

---

Is your feature request related to a problem?

Yes. Swagger UI always displays all schema fields, even when many fields are relevant only under specific conditions.

This causes confusion in two major scenarios:

---

1. Enum-based conditional fields (example)

Users select an enum value such as:

• content_type = FILE

• content_type = HTML

• content_type = INTERNAL_LINK

But Swagger UI still shows all fields, even when only one field is actually valid.

For example:

content_type | Valid Field That Should Show | Fields That Should Hide -- | -- | -- FILE | file | content_value, url HTML | content_value | file, url INTERNAL_LINK / EXTERNAL_LINK | url | file, content_value

Instead, users see everything at once, often leading to invalid submissions.

---

2. General if–else logic (example)

Example:

• If is_advanced = true, advanced_settings should appear.

• If is_advanced = false, advanced_settings should be hidden.

Swagger UI cannot express this behavior, even though the API depends on it.

---

Describe the solution you'd like

I would like Swagger UI to support dynamic conditional field rendering, based on both:

A. Enum Selection

Visibility updates depending on enum values.

Example:

x-visibility:
  when:
    field: content_type
    equals: FILE
  show: [file]
  hide: [content_value, url]

B. General If–Else Logic

Visibility or requirement changes based on any field value (boolean, string, number, enum, etc.)

Example:

x-conditional:
  when:
    field: is_advanced
    equals: true
  show: [advanced_settings]
  hide: []

Desired UI Behavior

• Selecting FILE instantly hides non-file fields.

• Selecting HTML shows only the HTML input field.

• Toggling a boolean shows or hides dependent fields.

• Swagger UI updates in real time, like a modern smart form.

This would prevent invalid requests and make the UI far more intuitive.

---

Describe alternatives you've considered

• Using oneOf with multiple schemas
  → Leads to repeated fields, breaks in multipart/form-data, not user-friendly.

• Adding documentation text like “Ignore this field when…”
  → Users still fill wrong fields.

• Injecting custom JavaScript to hide fields manually
  → Not maintainable, breaks with UI updates.

---

Additional context

Conditional logic is a standard feature in many form-driven interfaces (React forms, Angular forms, etc.).
Many APIs require logic such as:

• "If field A = X, show fields B and C"

• "If field A = Y, require field D"

• "These fields are mutually exclusive"

Supporting this in Swagger UI would:

• Remove confusion

• Reduce client errors

• Improve API onboarding

• Make complex schemas easier to understand

This enhancement would be extremely valuable for APIs involving structured or mode-based input (file uploads, content types, toggles, different data modes, etc.).

No source files or tests are named in the issue. Start with the SwaggerUI configuration and the provided OpenAPI schema examples, then trace the existing field-rendering entry point. Done means fields and requirements update dynamically for enum and general if–else conditions without showing irrelevant inputs.