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