Swagger UI / ReDoc for Interactive API Documentation Setup
Swagger UI and ReDoc turn OpenAPI specification into readable documentation with examples and ability to test API right from browser. They are not alternatives—they solve different tasks and are often used together.
Swagger UI vs ReDoc
Swagger UI — interactive documentation with "Try it out" button. Developer enters parameters and sends real API request right from browser. Indispensable during development and integration debugging.
ReDoc — beautiful readable reference. Three-column layout: navigation, description, example. No "Try it out", but better readable on mobile and prints well. Suits public documentation.
Scalar — modern alternative to both: ReDoc beauty + Swagger UI interactivity. Supports OAS 3.1. Recommended for new projects.
Backend integration
Express.js:
import swaggerUi from 'swagger-ui-express';
import swaggerJsdoc from 'swagger-jsdoc';
const spec = swaggerJsdoc({
definition: {
openapi: '3.1.0',
info: { title: 'My API', version: '1.0.0' },
},
apis: ['./routes/**/*.js'],
});
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec, {
customCss: '.swagger-ui .topbar { display: none }',
swaggerOptions: { persistAuthorization: true },
}));
FastAPI — Swagger UI available at /docs, ReDoc at /redoc automatically. For Scalar:
from scalar_fastapi import get_scalar_api_reference
@app.get("/scalar", include_in_schema=False)
async def scalar_html():
return get_scalar_api_reference(openapi_url="/openapi.json", title="API Reference")
Laravel + Scramble — package automatically registers /docs/api route with Stoplight Elements interface.
Customization and authentication
For Bearer token authentication, configure persistAuthorization in Swagger UI—token persists across page reloads. In ReDoc, add x-logo and x-tagGroups in info section of OpenAPI spec to organize navigation by groups.
info:
x-logo:
url: 'https://example.com/logo.png'
x-tagGroups:
- name: Core
tags: [users, projects]
- name: Billing
tags: [subscriptions, invoices]
Documentation hosting
Three options: embed in application (path /docs), deploy as separate static site, use hosted service (SwaggerHub, Readme.io).
Static option is most reliable. Export OpenAPI spec in CI, deploy Scalar/ReDoc as static to GitHub Pages or Cloudflare Pages.
Timeline
Connecting Swagger UI or ReDoc to existing application — 0.5–1 day. Custom styling and authentication setup — 1 day. Migration to Scalar with custom domain setup — 1–2 days.