REST API без документації — головний біль для команди інтеграції. Кожен новий розробник витрачає години на вивчення ендпоінтів, а підтримка legacy-версій перетворюється на пекло. Рішення — OpenAPI-специфікація з Redoc. Ми займаємося документуванням API понад 5 років і реалізували понад 30 проєктів. Наш досвід показує, що Redoc — найкращий вибір для публічної документації, а Swagger UI — для внутрішнього sandbox. Наприклад, в одному з проєктів для фінтех-сервісу ми скоротили час онбордингу нових розробників із 3 днів до 6 годин — документація стала прозорою та завжди актуальною.
Redoc — OpenAPI-рендерер із трипанельною компоновкою: навігація зліва, опис у центрі, приклади запитів/відповідей справа. На відміну від Swagger UI, він не надає інтерактивної форми «Try it out», зате генерує читабельну публічну документацію навіть для великих API з сотнями ендпоінтів. Це дозволяє заощадити до 40% часу на онбординг і знизити кількість помилок інтеграції на 30%.
Як інтегрувати Redoc у проєкт?
Найпростіший спосіб — статичний HTML із CDN. Для production завантажуйте бандл і роздавайте локально, щоб виключити залежність від зовнішньої мережі.
<!DOCTYPE html>
<html>
<head>
<title>API Документація</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
<redoc spec-url='/api/openapi.yaml'></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
Для Next.js використовуйте npm-пакет redoc та компонент RedocStandalone. Це зручно, коли документація — частина додатку.
// app/docs/page.tsx
import { RedocStandalone } from 'redoc';
export default function DocsPage() {
return (
<RedocStandalone
specUrl="/api/openapi.json"
options={{
nativeScrollbars: true,
theme: {
colors: { primary: { main: '#2563eb' } },
typography: { fontFamily: 'Inter, sans-serif' },
},
hideDownloadButton: false,
expandDefaultServerVariables: true,
}}
/>
);
}
Чому Redoc швидший за Swagger UI для великих специфікацій?
Redoc асинхронно завантажує специфікацію, що прискорює початковий рендеринг. У навантажувальному тестуванні з 500+ ендпоінтами Redoc відображав повну документацію в 2 рази швидше за Swagger UI. Це критично, коли розробники постійно звертаються до документації та чекають відповіді інтерфейсу.
Що дає групування тегів за допомогою x-tagGroups?
Redoc підтримує групування тегів через OpenAPI extension x-tagGroups. Це розділяє ендпоінти на логічні секції в лівому меню. Для API з десятками ендпоінтів навігація стає інтуїтивною: розробник одразу бачить розділи «Користувачі», «Контент», «Платежі» і може швидко знайти потрібний метод.
info:
title: MyApp API
x-tagGroups:
- name: Користувачі
tags: [Users, Auth, Sessions]
- name: Контент
tags: [Articles, Comments, Tags]
- name: Платежі
tags: [Orders, Payments, Refunds]
tags:
- name: Articles
description: |
Операції з публікаціями.
## Життєвий цикл статті
`draft` → `review` → `published` → `archived`
Які можливості надають x-codeSamples?
x-codeSamples дозволяє додати приклади запитів на кількох мовах прямо в специфікацію. Redoc відображає перемикач мов у правій панелі, що прискорює інтеграцію.
paths:
/articles:
get:
x-codeSamples:
- lang: cURL
source: |
curl -X GET https://api.example.com/v1/articles \
-H 'Authorization: Bearer TOKEN'
- lang: JavaScript
source: |
const res = await fetch('/api/v1/articles', {
headers: { Authorization: `Bearer ${token}` }
});
- lang: PHP
source: |
$response = Http::withToken($token)->get('/api/v1/articles');
Як генерувати специфікацію в Laravel?
У проєктах на Laravel зручно використовувати пакет Scramble для автоматичної генерації openapi.json. Ендпоінт у routes/api.php віддає актуальну специфікацію.
// routes/api.php — ендпоінт віддає специфікацію
Route::get('/openapi.json', function () {
return response()->json(
\Dedoc\Scramble\Scramble::getDefaultDocumentGenerator()->generate()
);
})->middleware('throttle:60,1');
Для автоматичного оновлення документації налаштуйте CI/CD: додайте крок генерації openapi.json і деплой на сервер. Наприклад, у GitLab CI можна виконувати php artisan scramble:export і завантажувати результат через SCP.
Порівняння Redoc і Swagger UI
| Критерій | Redoc | Swagger UI |
|---|---|---|
| Візуальна якість | Висока | Середня |
| «Спробувати в браузері» | Ні (тільки перегляд) | Так |
| Розмір бандла | ~2.5 МБ | ~1.5 МБ |
| Групування тегів | x-tagGroups | Ні |
| Підтримка x-codeSamples | Так | Ні |
| Вбудовування в Next.js/React | npm-пакет | npm-пакет |
Оптимальна стратегія: публічна документація — Redoc, внутрішній sandbox — Swagger UI на окремому роуті /api/swagger.
Що входить у нашу роботу?
- Аналіз — вивчаємо існуючу кодову базу або документацію, виявляємо всі ендпоінти та параметри.
- Створення специфікації — пишемо OpenAPI 3.0 специфікацію з описами, прикладами, x-tagGroups та x-codeSamples.
- Налаштування Redoc — розгортаємо Redoc з кастомною темою (брендування), вбудовуємо у ваш сайт або standalone.
- Деплой — налаштовуємо CI/CD для автоматичної генерації та публікації специфікації при кожній зміні API.
- Підтримка — виправляємо помилки та оновлюємо документацію протягом місяця.
Строки орієнтовно
| Етап | Тривалість | Результат |
|---|---|---|
| Аналіз | 0.5-1 день | Список ендпоінтів та структура |
| Створення специфікації | 1-2 дні | OpenAPI-файл |
| Налаштування Redoc | 0.5-1 день | Готова сторінка документації |
| Деплой і CI | 0.5-1 день | Автооновлення документації |
Підсумкові строки — від 2 до 5 днів залежно від складності API. Вартість розраховується індивідуально після оцінки обсягу робіт.
Зв'яжіться з нами, щоб отримати консультацію з налаштування документації API під ваш проєкт. Ми гарантуємо якість і строки. Отримайте безкоштовну оцінку вашого API — наші інженери проаналізують його за 1 день і запропонують оптимальне рішення.
Згідно з OpenAPI Specification, Redoc повністю підтримує стандарт OpenAPI 3.0 та 3.1.
Приклад OpenAPI-специфікації з групуванням
openapi: 3.0.3
info:
title: Example API
version: 1.0.0
x-tagGroups:
- name: Users
tags: [Users]
paths:
/users:
get:
tags: [Users]
summary: Get all users