What is the difference between Swagger UI and Redoc for rendering an OpenAPI document?

## Same input, different jobs Both tools take an OpenAPI document and produce an HTML page. Everything they display — endpoint list, parameter tables, schema trees, sample payloads, prose — is read from the document. Neither invents information, which is the first thing to internalise: if the rendered docs are thin, the fix is in the spec, not the renderer. ## Swagger UI: the interactive explorer Swagger UI presents operations grouped by tag, each expandable to show parameters, request body, responses and schemas. Its distinguishing feature is **Try it out**: you fill in parameters, click execute, and the page issues a real HTTP request from the browser to the selected server, then shows the status, headers and body — plus the equivalent `curl` command. Three consequences follow from that being a real request: - **It hits a real server.** Executing against a production server from a docs page performs actual writes. Teams either point the page at a sandbox, restrict the server list, or disable the feature on public docs. - **CORS applies.** The browser is making a cross-origin request, so the API must return permissive CORS headers or every attempt fails with an opaque network error. This is the single most common "Try it out doesn't work" cause. - **Credentials are entered into the page.** An authorize dialog collects a token or key according to the document's declared security schemes, which is fine internally and a poor idea on a public page. Swagger UI is bundled by many server frameworks so that a running service exposes its own explorer, which is why most developers meet it first as "the page at `/swagger-ui`". ## Redoc: the published reference Redoc renders a three-panel layout: a navigation tree on the left, prose and parameter/schema detail in the middle, and request/response samples on the right. It does not send requests. The result reads like reference documentation rather than a console — long-form descriptions get room, schemas are browsable, and the page is a single artefact you can host statically. That static, read-only nature is the point. Public API documentation usually wants a stable, linkable, well-typeset reference; it does not want an anonymous visitor firing requests at your service. Redoc also leans on rich `description` fields and Markdown, so it rewards specs written with prose in mind. ## Choosing between them A common arrangement is both: Swagger UI on internal or non-production environments where hands-on exploration is the goal, and a Redoc-rendered page published for consumers. They are not exclusive — the document is one artefact, and rendering it twice costs nothing but a build step. Pick Swagger UI when the audience is developers integrating right now, against an environment where making calls is safe. Pick Redoc when the audience is reading to understand, when the page is public, or when you want documentation you can publish as static files. ## What neither gives you A rendered spec is *reference* documentation. It answers "what fields does this endpoint take" and never "how do I authenticate, what is the rate-limit policy, what is the recommended integration sequence". Those belong in hand-written guides alongside the generated reference. Teams that ship only a rendered spec and call it documentation reliably get the same integration questions over and over. Equally, neither tool verifies that the document matches the running service. A beautifully rendered page can describe an API that no longer exists; keeping the two aligned is a pipeline problem, not a rendering one. ## Practical quality levers Because both renderers only surface what is in the document, the levers are all in the spec: meaningful `summary` and `description` on every operation, `example` or `examples` on request bodies and responses so samples are realistic rather than `"string"`, sensible tags because both tools group by them, and named components so the schema panel shows recognisable model names instead of anonymous inline shapes.