# Interactive Documentation: Swagger UI, Redoc and Scalar — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/t-docs

> Publish readable, interactive API documentation from OpenAPI documents.

## Docs generated from the contract

Several tools render OpenAPI documents as documentation websites. **Swagger UI** shows operations grouped by tag with an interactive **"Try it out"** feature that sends real requests, including authentication via the declared security schemes. **Redoc** produces a clean three-panel reference layout that is popular for public API portals. **Scalar** and other modern renderers combine reference docs with built-in API clients. **Swagger Editor** shows a live preview while you edit YAML, with validation errors highlighted. Many API gateways and developer portals (Azure API Management, AWS API Gateway, Kong, Backstage) import OpenAPI documents too. Make documentation genuinely useful: write descriptions in Markdown with context, not just field names; provide realistic examples; tag operations logically; explain authentication, rate limits, pagination and error handling in `info.description` or tag descriptions; and publish docs from the same CI pipeline that validates the document so they never drift from the deployed API.

## Docs rendered from the document

The same YAML becomes a reference site with examples and a try-it-out console.

![A YAML document icon on the left with an arrow to a browser window showing a sidebar, content panel and code panel.](assets/figures/openapi/section-6-map.svg) — Figure 6.1 — Rendering an OpenAPI document as interactive documentation.

## Serving Swagger UI and Redoc for the same document

Two static pages pointing at one openapi.yaml.

```html
<!-- swagger.html -->
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
  </head>
  <body>
    <div id="swagger"></div>
    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
    <script>
      SwaggerUIBundle({ url: '/openapi.yaml', dom_id: '#swagger', persistAuthorization: true });
    </script>
  </body>
</html>

<!-- redoc.html -->
<!doctype html>
<html>
  <body>
    <redoc spec-url="/openapi.yaml"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>
```

## Protect try-it-out in production

Interactive docs against production let anyone with credentials make real calls, including destructive ones. Point try-it-out at a sandbox environment, or disable it for public production docs.

**Quiz:** Which feature is Swagger UI best known for?

- [ ] Generating database schemas
- [ ] Running load tests
- [x] Interactive "Try it out" requests from the documentation
- [ ] Compiling Java code

*Answer:* Interactive "Try it out" requests from the documentation. Swagger UI lets readers send real requests directly from the rendered docs.