Документація API (Redoc) для веб-застосунку
Redoc — це OpenAPI-рендерер з трипанельним макетом: навігація зліва, опис в центрі, приклади запитів/відповідей справа. На відміну від Swagger UI, Redoc не забезпечує інтерактивну форму «Спробувати», але генерує читабельну публічну документацію навіть для великих API з сотнями ендпоїнтів.
Вбудовування Redoc
Найпростіший спосіб — статичний HTML з CDN:
<!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>
Для production — завантажити бандл та розповсюджувати локально. CDN створює залежність від зовнішної мережі.
Самостійне розміщення через npm
npm install redoc
Інтеграція з Next.js (статичний маршрут /docs):
// 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,
}}
/>
);
}
Конфігурація через x-tagGroups
Redoc підтримує групування тегів через розширення OpenAPI, відображаючи їх як розділи в лівому меню:
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`
Опис тегів підтримує повний Markdown — можна додавати схеми, таблиці, посилання.
x-codeSamples — Приклади коду кількома мовами
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');
Redoc показує перемикач мов у правій панелі.
Генерування openapi.json у Laravel
// routes/api.php — ендпоїнт повертає специфікацію
Route::get('/openapi.json', function () {
return response()->json(
\Dedoc\Scramble\Scramble::getDefaultDocumentGenerator()->generate()
);
})->middleware('throttle:60,1');
Альтернатива — експортувати статичний файл у CI:
php artisan scramble:export --output=public/openapi.json
Redoc CLI для статичної генерації
npx @redocly/cli build-docs openapi.yaml --output docs/index.html
Отриманий index.html (~3 МБ з вбудованим бандлом) розгортається на будь-якому статичному хостингу (S3, GitHub Pages, Cloudflare Pages). Не потребує сервера.
Redoc vs Swagger UI — Коли вибирати
| Критерій | Redoc | Swagger UI |
|---|---|---|
| Якість візуалізації | Висока | Середня |
| «Спробувати в браузері» | Ні (тільки перегляд) | Так |
| Розмір бандлу | ~2.5 МБ | ~1.5 МБ |
| Групування тегів | x-tagGroups | Ні |
| Підтримка x-codeSamples | Так | Ні |
| Інтеграція в Next.js/React | npm-пакет | npm-пакет |
Оптимальна стратегія: публічна документація — Redoc, внутрішній sandbox для розробників — Swagger UI на окремому маршруті /api/swagger.
Терміни
Налаштування Redoc з пользувацькою темою, групуванням тегів та прикладами коду: 0.5–1 день. Інтеграція з CI (автоекспорт openapi.json, розгортання на Cloudflare Pages): 1 додатковий день.