How do I get a static Swagger UI build?

Take the `swagger-ui-dist` package contents, point `swagger-initializer.js` at your spec file, and upload the directory — spec included — so everything resolves against the uploaded copies rather than a server you have to run.

Does the spec need to be reachable over the network?

No, and it should not be for a private review. Upload `openapi.yaml` alongside the UI files and reference it relatively. A spec fetched from a URL only works if that URL is reachable from the reviewer's browser.

Does Try-It-Out work at the link?

It will attempt the request from the reviewer's browser, which means it works only if your API is reachable from there and allows the origin. For a private spec review that is usually not what you want; the value here is the rendered documentation.

Why review the rendered docs at all?

Because descriptions, examples and response shapes are prose and structure, and both are reviewed badly as a YAML diff. Rendered, a missing error case or a wrong example is obvious in seconds.

How do reviewers give feedback?

Anchored threads on the operation or the schema field. The comment stays attached across revisions, so a note on the 409 case is still there after the next spec build.

Share Swagger UI docs

Reviewing an OpenAPI change as a YAML diff is a way of not reviewing it. The parts most likely to be wrong — the description, the example payload, whether the error responses are complete — are the parts a diff renders worst.

Rendered in Swagger UI, the same change takes ninety seconds to review properly. The friction is that rendering it means serving it.

Publish it

Assemble a static build and upload the directory:

mkdir -p swagger-build
cp -r node_modules/swagger-ui-dist/* swagger-build/
cp openapi.yaml swagger-build/
# point the initializer at the local spec
sed -i.bak 's|https://petstore.swagger.io/v2/swagger.json|openapi.yaml|' \
  swagger-build/swagger-initializer.js

Drag swagger-build/ into the app: index.html becomes the report body, and the JS, CSS and the spec file upload as assets with their references rewritten to the uploaded copies. That rewrite is the part that matters — a Swagger UI page whose spec URL still points at a localhost server renders an error, not documentation.

Scripts run inside a sandboxed iframe, so navigation and schema expansion work at the link.

A note on Try It Out

The Try-It-Out button fires a request from the reviewer's browser to whatever server the spec declares. That works only if the API is reachable from there and permits the origin. For a pre-merge spec review it usually is not, and does not need to be — the thing being reviewed is the documentation.

What the URL changes

Feedback on the operation. "The 409 case is missing" pinned to the endpoint. See commenting on HTML.
Reviewers who are not engineers. Support, partners, the team integrating against you.
A revision per spec build. Same URL, full history. See revisions and diffs.
Private by default — an unreleased API surface is not something to leave on a guessable URL. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total — swagger-ui-dist ships source maps you can drop before uploading.
Scripts run, sandboxed: allow-scripts, no allow-same-origin.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Create your first report →

Redoc builds — one file, no assembly
OpenAPI docs · Share with a client
Publish from CI · Password-protected links