Налаштування Swagger UI / ReDoc для інтерактивної документації API

Коли API розростається до сотень ендпоінтів, ручна документація стає ахіллесовою п'ятою проєкту

Партнери скаржаться на незрозумілі відповіді, розробники витрачають години на пошук потрібного методу — ми стикаємося з цим на кожному другому проєкті. Налаштування Swagger UI, ReDoc або Scalar вирішує проблему за 0,5–2 дні. Інтерактивна документація з кнопкою Try it out, автентифікацією та кастомним дизайном — стандарт сучасної розробки. Ми усунули ці проблеми в 30+ проєктах — від стартапів до enterprise-систем, скоротивши час інтеграції в 2–3 рази та заощадивши клієнтам сотні тисяч гривень на рік на підтримці.

Проблеми, які вирішуємо

Ручна документація застаріває через два тижні — факт. Згідно зі специфікацією OpenAPI, вона живе разом із кодом, а інструменти на кшталт Swagger UI та ReDoc перетворюють її на інтерактивний довідник без жодного редагування вручну. Типові помилки: не налаштовано CORS (запити з Swagger UI летять у порожнечу), відсутній persistAuthorization (токен скидається при кожному перезавантаженні) або документація не оновлюється в CI пайплайні. Ми усуваємо ці проблеми ще на етапі підключення. Результат — скорочення часу інтеграції в 2–3 рази. В одному проєкті для фінтех-стартапу ми розгорнули Scalar із кастомним доменом та авторизацією — команда перестала витрачати 10 годин на тиждень на пояснення інтеграторам, а навантаження на підтримку знизилося на 60%.

Процес налаштування документації API за 4 кроки

Ми дотримуємося чіткого процесу, щоб гарантувати актуальність та зручність документації:

1. Аналіз API: вивчаємо специфікацію, ендпоінти, схеми даних.
2. Вибір інструменту: Swagger UI для розробки, ReDoc або Scalar для публічної документації.
3. Підключення та кастомізація: налаштування стилів, автентифікації, CI/CD.
4. Деплой та підтримка: розміщення на хостингу, автоматичне оновлення при кожному деплої.

Як підключити Swagger UI до вашого API?

Для Express.js використовуємо зв'язку swagger-jsdoc та swagger-ui-express. Генеруємо специфікацію з JSDoc анотацій, реєструємо роут /docs — документація готова за 15 хвилин:

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 документація на /docs та /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.

Що обрати: Swagger UI, ReDoc чи Scalar?

Swagger UI ідеальний для розробки та налагодження: кнопка Try it out дозволяє надсилати запити прямо з браузера. ReDoc краще читається на мобільних пристроях і підходить для публічної документації. Scalar — сучасна альтернатива, що поєднує інтерактивність Swagger UI та зручність читання ReDoc. Усі три підтримують OpenAPI 3.1, але Scalar швидше завантажується та пропонує більш гнучку кастомізацію. Наприклад, в одному проєкті ми перейшли з Swagger UI на Scalar та отримали зниження часу завантаження сторінки документації на 40%.

Терміни налаштування по етапах

Що входить у роботу під ключ

Ми — команда з багаторічним досвідом, що виконала понад 30 проєктів з налаштування API документації. Беремо на себе повне супроводження:

• генерація OpenAPI специфікації за вашим API;
• підключення та налаштування Swagger UI / ReDoc / Scalar;
• кастомізація стилів під бренд (лого, кольори);
• налаштування автентифікації (Bearer token, OAuth2) з persistAuthorization;
• інтеграція в CI/CD (автоматичне оновлення при деплої);
• хостинг документації (статичний сайт на будь-якому майданчику).

Гарантуємо, що документація буде актуальною на момент здачі.

Кастомізація та автентифікація

Для API з Bearer token налаштовуємо persistAuthorization у Swagger UI — токен зберігається між перезавантаженнями. У ReDoc додаємо x-logo та x-tagGroups для групування ендпоінтів. Приклад OpenAPI специфікації:

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

Як забезпечити оновлення документації при деплої?

Додайте крок у пайплайн, який генерує OpenAPI spec і деплоїть статичну документацію. Ми використовуємо GitHub Actions або GitLab CI для автоматизації — це гарантує, що документація завжди синхронізована з кодом. Приклад конфігурації надаємо.

Хостинг документації

Три варіанти: вбудувати в додаток (шлях /docs), задеплоїти як окремий статичний сайт, використовувати hosted сервіс (SwaggerHub, Readme.io). Статичний варіант — найнадійніший: експортуємо OpenAPI spec у CI, деплоїмо Scalar/ReDoc на GitHub Pages або Cloudflare Pages. Документація завжди доступна і не залежить від працездатності сервера API.

Терміни

Підключення базового Swagger UI або ReDoc до існуючого додатку — 0,5–1 день. Налаштування кастомного стилю та автентифікації — 1 день. Міграція на Scalar із кастомним доменом — 1–2 дні. Замовте налаштування документації API під ключ — отримайте консультацію безплатно. Зв'яжіться з нами, щоб обговорити деталі вашого проєкту та оцінити економію бюджету.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.