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

[SaarthakMaini]

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.).