Configuring Swagger UI / ReDoc for Interactive API Documentation

When API grows to hundreds of endpoints, manual documentation becomes the project's Achilles' heel

Partners complain about unclear responses, developers spend hours searching for the right method — we encounter this on every second project. Setting up Swagger UI, ReDoc, or Scalar solves the problem in 0.5–2 days. Interactive documentation with a Try it out button, authentication, and custom design is the standard of modern development. Over 5 years, we have eliminated these problems in 30+ projects — from startups to enterprise systems — reducing integration time by 2–3 times and saving clients hundreds of thousands of rubles per year on support.

Problems we solve

Manual documentation becomes outdated after two weeks — a fact. According to the OpenAPI specification, it lives with the code, and tools like Swagger UI and ReDoc turn it into an interactive reference without a single manual edit. Typical mistakes: CORS not configured (requests from Swagger UI go into the void), missing persistAuthorization (token resets on every reload), or documentation not updated in the CI pipeline. We eliminate these problems already at the connection stage. The result is a reduction in integration time by 2–3 times. In one project for a fintech startup, we deployed Scalar with a custom domain and authorization — the team stopped spending 10 hours per week explaining to integrators, and support load dropped by 60%.

Process of setting up API documentation in 4 steps

We follow a clear process to guarantee the documentation is up-to-date and user-friendly:

1. API Analysis: study the specification, endpoints, data schemas.
2. Tool selection: Swagger UI for development, ReDoc or Scalar for public documentation.
3. Connection and customization: configure styles, authentication, CI/CD.
4. Deployment and support: host, automatic update on every deploy.

How to add Swagger UI to your API

For Express.js, we use the swagger-jsdoc and swagger-ui-express bundle. We generate the specification from JSDoc annotations, register the /docs route — documentation is ready in 15 minutes:

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 }, })); 

In FastAPI, documentation at /docs and /redoc appears automatically. If you need Scalar, three lines of code:

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") 

For Laravel, we recommend the Scramble package — it registers the /docs/api route with a Stoplight Elements interface.

What to choose: Swagger UI, ReDoc, or Scalar?

Swagger UI is ideal for development and debugging: the Try it out button lets you send requests directly from the browser. ReDoc is better for mobile reading and suitable for public documentation. Scalar is a modern alternative that combines Swagger UI's interactivity with ReDoc's readability. All three support OpenAPI 3.1, but Scalar loads faster and offers more flexible customization. For example, in one project we switched from Swagger UI to Scalar and reduced the documentation page load time by 40%.

Timeline by stages

What's included in a turnkey solution

We are a team with more than 5 years of experience and have completed over 30 projects on API documentation setup. We take full responsibility:

• generation of OpenAPI specification for your API;
• connection and configuration of Swagger UI / ReDoc / Scalar;
• style customization under your brand (logo, colors);
• authentication setup (Bearer token, OAuth2) with persistAuthorization;
• CI/CD integration (automatic update on deploy);
• documentation hosting (static site on any platform).

We guarantee that the documentation will be up-to-date upon delivery.

Customization and authentication

For APIs with Bearer token, we configure persistAuthorization in Swagger UI — the token persists between reloads. In ReDoc, we add x-logo and x-tagGroups for grouping endpoints. Example OpenAPI specification:

info: x-logo: url: 'https://example.com/logo.png' x-tagGroups: - name: Core tags: [users, projects] - name: Billing tags: [subscriptions, invoices] 

How to keep documentation updated on deploy?

Add a step in the pipeline that generates the OpenAPI spec and deploys static documentation. We use GitHub Actions or GitLab CI for automation — this guarantees that the documentation is always synchronized with the code. We provide an example configuration.

Hosting documentation

Three options: embed in the application (path /docs), deploy as a separate static site, or use a hosted service (SwaggerHub, Readme.io). The static option is the most reliable: we export the OpenAPI spec in CI, deploy Scalar/ReDoc to GitHub Pages or Cloudflare Pages. Documentation is always available and does not depend on the API server's uptime.

Timeline

Basic Swagger UI or ReDoc setup for an existing application — 0.5–1 day. Custom style and authentication — 1 day. Migration to Scalar with custom domain — 1–2 days. Request turnkey API documentation setup — get a free consultation. Contact us to discuss your project details and evaluate budget savings.