swagger-api / swagger-api/swagger-ui

Virtualization breaks browser Find (Cmd+F) for non-visible operations and schemas

Open
#11,056 0 comments 1 reaction 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: macOS
Browser: Firefox 155 / Chrome [version]
Version: [browser version]
Method of installation: npm / dist assets [whichever applies]
Swagger-UI version: 5.33.0
Swagger/OpenAPI version: OpenAPI 3.x

Content & configuration

Example Swagger/OpenAPI definition:

  • A large OpenAPI definition containing enough operations/schemas for the virtualization to take effect.
Describe the bug you're encountering

Since Swagger UI 5.33.0, the newly introduced virtualization for operations and schemas means that only items currently within the viewport are rendered in the DOM. As a result, the browser's native Find feature (Cmd+F on macOS) can no longer find operations or schemas that have not yet been rendered.

For large API definitions, this significantly impacts the ability to quickly navigate the documentation. Before 5.33.0, Cmd+F could search the entire rendered Swagger UI page and immediately locate a matching endpoint, schema, etc. With virtualization enabled, a matching item outside the current viewport is not present in the DOM, so the browser cannot find it.

This is particularly problematic because there does not appear to be an equivalent built-in search/navigation mechanism that can search the complete set of operations and schemas and jump directly to the matching item.

In other words, I guess the virtualization improves rendering performance for large specifications, but it also removes an important existing way of discovering and navigating the documentation.

To reproduce...
  • 1 Open Swagger UI 5.33.0 with a sufficiently large OpenAPI definition containing many operations.
  • 2 Make sure the target operation is far enough down the page that it is initially outside the viewport.
  • 3 Use the browser's native Find feature (Cmd+F on macOS).
  • 4 Search with a keyword to the endpoint path. Observe that the browser cannot find the operation.
  • 5 Scroll down until the operation is rendered.
  • 6 Repeat the same search and observe that the browser can now find it.
Expected behavior

Browser-native Find should remain usable for navigating the complete Swagger UI documentation.

Alternatively, if virtualization intentionally prevents non-visible content from being present in the DOM, Swagger UI should provide an equivalent built-in search/navigation mechanism that searches the complete OpenAPI definition and can navigate directly to the matching operation or schema.

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 issue in Swagger UI 5.33.0 with a large OpenAPI definition and inspect how virtualization renders operations and schemas outside the viewport. Determine how complete-document search or navigation could work without losing virtualization; done means browser Find remains usable or an equivalent built-in mechanism finds and jumps to non-visible operations and schemas.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
documentation, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.