Настройка Swagger UI / ReDoc для интерактивной документации API
Swagger UI и ReDoc превращают OpenAPI спецификацию в читаемую документацию с примерами запросов и возможностью протестировать API прямо из браузера. Это не альтернативы — они решают разные задачи и часто используются вместе.
Swagger UI vs ReDoc
Swagger UI — интерактивная документация с кнопкой «Try it out». Разработчик вводит параметры и отправляет реальный запрос к API прямо из браузера. Незаменим при разработке и отладке интеграций.
ReDoc — красивый читаемый справочник. Трёхколоночный layout: навигация, описание, пример. Нет «Try it out», зато лучше читается на мобильных и хорошо печатается. Подходит для публичной документации.
Scalar — современная альтернатива обоим: красивый дизайн ReDoc + интерактивность Swagger UI. Поддерживает OAS 3.1. Рекомендуется для новых проектов.
Подключение к бэкенду
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 доступен на /docs, ReDoc на /redoc автоматически. Для 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 — пакет автоматически регистрирует маршрут /docs/api с интерфейсом Stoplight Elements.
Кастомизация и аутентификация
Для API с Bearer token аутентификацией настраиваем persistAuthorization в Swagger UI — токен сохраняется между перезагрузками страницы. В ReDoc добавляем x-logo и x-tagGroups в секцию info OpenAPI спецификации для организации навигации по группам.
info:
x-logo:
url: 'https://example.com/logo.png'
x-tagGroups:
- name: Core
tags: [users, projects]
- name: Billing
tags: [subscriptions, invoices]
Хостинг документации
Три варианта: встроить в приложение (путь /docs), задеплоить как отдельный статический сайт, использовать hosted сервис (SwaggerHub, Readme.io).
Статический вариант — самый надёжный. Экспортируем OpenAPI spec в CI, деплоим Scalar/ReDoc как статику на GitHub Pages или Cloudflare Pages.
Сроки
Подключение Swagger UI или ReDoc к существующему приложению — 0,5–1 день. Настройка кастомного стиля и аутентификации — 1 день. Миграция на Scalar с настройкой кастомного домена — 1–2 дня.