# Share Swagger UI Docs — A Reviewable Link for Your OpenAPI Spec

Canonical: https://commareports.com/share-swagger-ui-docs
Published: 2026-09-01

> Publish a Swagger UI build to Comma so reviewers read the rendered endpoints instead of the YAML, comment on the operation itself, and see each spec change as a revision at one URL.

# 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:

```bash
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](https://commareports.com/):
`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](/comment-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](/share-html-report).
- **Private by default** — an unreleased API surface is not something to
  leave on a guessable URL. See the [sharing model](/docs/sharing).

## 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 →](https://commareports.com/)**

### Related

- [Redoc builds](/share-redoc-api-docs) — one file, no assembly
- [OpenAPI docs](/share-openapi-docs) · [Share with a client](/share-html-file-with-client)
- [Publish from CI](/docs/ci) · [Password-protected links](/password-protect-html-report)