feat: Deep Search plugin for operation filtering across OpenAPI structures

[samuelfabel]

Content & configuration

Swagger/OpenAPI definition:

# Any reasonably sized OAS 2.0 / 3.x spec (e.g. Petstore)
openapi: 3.0.0
paths:
  /pets:
    get:
      summary: List pets
      tags: [pets]

Swagger-UI configuration options:

SwaggerUI({
  url: "https://petstore.swagger.io/v2/swagger.json",
  deepSearch: {
    enabled: true,
    allowRuntimeScopeSelection: true,
    // scopes: ["paths", "summaries", "parameters"], // optional
  },
})

Is your feature request related to a problem?

Yes. The built-in filter option only filters operations by tag name. On large API definitions, users often need to find operations by path segments, summaries, descriptions, parameter names, request/response fields, operationId, HTTP method, and similar content. Without that capability, discovering the right endpoint in Swagger UI is slow and error-prone.

Describe the solution you'd like

Add an optional Deep Search plugin to Swagger UI that extends operation filtering beyond tags while remaining compatible with the existing filter pipeline.

Goals

• Search across configurable OpenAPI structures (paths, tags, summaries, descriptions, parameters, request bodies, responses, schemas, examples, status codes, operationId).
• Opt-in via configuration (deepSearch.enabled, default false) so existing deployments are unchanged.
• Reuse the filter region UI pattern: a search input in the operations area; matching operations stay visible, non-matching operations are hidden (same mental model as filter).
• No new npm dependencies — fuzzy/partial matching and indexing implemented in-project; debounce via existing lodash/debounce.
• Follow the existing plugin architecture (src/core/plugins/deep-search/), registered in the base preset, exportable as SwaggerUI.plugins.DeepSearch.

Configuration (deepSearch object)

Property	Type	Default	Description
enabled	Boolean	false	Enables Deep Search
allowRuntimeScopeSelection	Boolean	true	Shows scope selector UI when true
scopes	Array or null	null	Initial or fixed list of scope keys

Searchable scopes (defaults)

• Enabled by default: paths, tags, summaries, descriptions, parameters, requestBodyFields, responseFields, operationId
• Disabled by default: schemas, examples, statusCodes
• Aliases: responses → responseFields, requestBody → requestBodyFields

Search behavior (high level)

• Case-insensitive; partial match within words/identifiers (e.g. cpf matches customerCpf).
• HTTP method queries (get, post, put, …) list operations for that method; method names use strict word matching in text fields to reduce false positives (e.g. post should not match positive).
• Pre-built in-memory index on spec load / scope change; debounced input (~300ms).
• Does not auto-expand matched operations (user expands manually).
• When both filter: true and deepSearch.enabled: true, apply tag filter first, then Deep Search.

Relationship to filter

filter	deepSearch.enabled	Result
false	false	No search input (default)
true	false	Legacy tag filter
*	true	Deep Search input

Describe alternatives you've considered

1. Extend the existing filter option — Would change semantics for all users who rely on tag-only filtering; a separate opt-in plugin/config is safer.
2. Browser-native find (Ctrl+F) — Does not understand OpenAPI structure or hide non-matching operations in the operations list.
3. Third-party search dependency (e.g. Fuse.js) — Adds bundle weight and maintenance; project preference is to avoid new dependencies for this feature.
4. Auto-expand all matches — Rejected for UX on large specs (too much visual noise); filtering visibility only.

Additional context

This is a UI/UX feature affecting the operations filter area. Happy to adjust scope defaults, copy, or interaction details based on maintainer / UX feedback before opening a PR.

Planned deliverables

• Plugin implementation under src/core/plugins/deep-search/
• Config in defaults.js + type casting
• SCSS for modal / scope selector
• Unit tests
• Docs: docs/usage/deep-search.md and deepSearch entry in configuration.md

I have a working implementation on a fork and will submit a PR referencing this issue once the approach is agreed upon.