Налаштування 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 дні.