fix: render OpenAPI 3.1 in the Tracy panel by moving Swagger UI to 5.32.12 - #17
Open
AdamFiser wants to merge 3 commits into
Open
fix: render OpenAPI 3.1 in the Tracy panel by moving Swagger UI to 5.32.12#17AdamFiser wants to merge 3 commits into
AdamFiser wants to merge 3 commits into
Conversation
The panel inlines its own copy of Swagger UI, and how that copy was produced was not recorded anywhere: the committed stylesheet is not the distributed one, because every selector carries a #tracy-debug scope the panel needs to avoid styling the host page around it. The tool downloads a given swagger-ui-dist release, stores the scripts verbatim and applies that scope itself. It aborts on a selector it cannot place instead of guessing, so a release that reaches outside the panel in a new way stops the update rather than reaching an application. Cover it by the existing checks, and keep it out of the distributed package.
The vendored Swagger UI was 3.24.2, built in November 2019, and its version
detection accepts the 3.0 series alone:
function s(e){var t=e.get("openapi");return"string"==typeof t&&(t.startsWith("3.0.")&&t.length>4)}
A document declaring openapi: 3.1.0 matched neither that nor the Swagger 2 test, so
the panel rendered "Unable to render this definition" for a document this library
produces, describes and validates. The message blamed the definition for specifying
no valid version field, which sent readers looking in the wrong place.
Swagger UI renders 3.1 from 5.0.0 on. Move to 5.32.12, produced by
tools/update-swagger-ui.php.
The stylesheet gained one rule that would reach past the panel: StandaloneLayout
puts .dark-mode on <html> itself, and html.dark-mode sets a background, so a
developer whose system asks for a dark theme would find the whole application
repainted. That rule is dropped; the remaining 3095 selectors are scoped.
The panel renders inside a host page, so a Swagger UI selector that escapes the debug bar styles someone's application. Nothing checked that, and the escape a 5.x stylesheet actually contains - html.dark-mode - takes a browser and a dark system theme to notice. Assert it from the stylesheet instead: every selector carries the scope, and the scope sits in front of .swagger-ui so the descendant chains Swagger UI relies on survive. Assert too that the bundle is a release which renders 3.1 at all, since that is the property the panel was failing on. Document the version the panel carries and how to move it.
AdamFiser
marked this pull request as ready for review
August 11, 2026 07:26
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements option A of #16: the Tracy panel now renders the OpenAPI 3.1 documents this library produces.
The vendored Swagger UI was 3.24.2 (November 2019), whose version detection accepts the 3.0 series alone, so
openapi: 3.1.0fell through to "Unable to render this definition". Swagger UI renders 3.1 from 5.0.0 on; this moves the copy to 5.32.12.What is here
tools/update-swagger-ui.php— the update is reproducible instead of folklore. The committed stylesheet is not the distributed one (every selector carries a#tracy-debugscope, or the panel would style the host page around it), and nothing recorded how that was produced. The tool downloads a givenswagger-ui-distrelease, stores the two scripts verbatim and applies the scope itself:It refuses to guess. A selector it cannot place aborts the run — which is not hypothetical: the first run stopped on the trailing
sourceMappingURLcomment, and that is the behaviour that will catch the next release reaching outside the panel.One rule had to be dropped.
StandaloneLayoutputs.dark-modeon<html>itself:Paired with
html.dark-mode{background:#1c2022}, any developer whose system asks for a dark theme would have found their whole application repainted whenever the bar was on the page. The rule is dropped and the tool says so on every run.tests/Cases/Tracy/SwaggerUiAssetsTest.php— asserts from the stylesheet that every selector carries the scope, that the scope sits in front of.swagger-uiso Swagger UI's descendant chains survive, and that the bundle is a release which renders 3.1 at all.toolsis now covered bymake cs/make phpstanand carriesexport-ignore.Verification
Green tests are not the evidence here — a green suite is exactly what let this go unnoticed. So the panel was actually rendered:
tests/Cases/Schema/examples/complete-3-1.yamlthroughOpenApi::fromArray(...)->toArray()(which yieldsopenapi: 3.1.0), passed to the realSwaggerPanel::getPanel(), inside a host page with its own background, in headless Chrome.<html>backgroundrgb(255, 255, 255)--force-dark-mode)rgb(255, 255, 255)In the dark run
<html class="dark-mode">is set by Swagger UI, yet the host background is untouched — the dropped rule doing its job. Among the nine rendered operations is thepetCreatedwebhook, a construct that exists only in 3.1, so this is 3.1 being rendered as 3.1 rather than tolerated.I have the rendered screenshot locally and can attach it here on request — the panel shows the servers block with its variables, the
petsanddefaulttag groups across all eight methods, a Webhooks section holdingpetCreated, and thePetschema. Note that.docs/misc/tracy-panel.pngstill shows the older UI; I left it alone rather than replace a screenshot taken in a real application with a staged imitation.Checks:
The scoping test was also confirmed to fail when the scoping is broken — appending
html.dark-mode{background:red}to the stylesheet producesFailed: These selectors would style the host page.: ['html.dark-mode']— and the version test fails when the 3.24.2 bundle is put back.Cost
The inlined payload grows from ~1.42 MB to ~2.00 MB per page carrying the Tracy bar, since
panel.phtmlreads all three assets on every render. Worth stating plainly, as #16 does: it buys rendering the versions the library supports, in a development-only tool.Closes #16 if you take this route. Happy to fold in the version-warning idea (option C) as well, or to change the scoping approach, if you would rather have it another way.