Как вы уже наверняка заметили, мир API не терпит хаоса, и потребность в структурированной и детализированной документации API встаёт на первый план. Мы уже познакомились с таким инструментом документирования, как Swagger, и теперь пора изучить его главного конкурента — Redoc. Чем отличается этот инструмент, какие у него преимущества и как его использовать в проекте? Время разбираться!
Что такое Redoc?
Redoc — это инструмент для документирования API, который использует спецификацию OpenAPI (ранее известную как Swagger Specification). Он предоставляет удобный и современный интерфейс для просмотра API-документации и фокусируется на удобстве восприятия для разработчиков.
Преимущества Redoc
Интерфейс Redoc выглядит очень свежо, минималистично и профессионально. Если Swagger UI напоминает доску объявлений с кучей кнопок, то Redoc предлагает плавные переходы и структурированное представление данных.
Поддержка спецификаций OpenAPI. Redoc поддерживает спецификации OpenAPI версий 2.0 и 3.0. Это означает, что если у вас уже есть спецификация в формате OpenAPI, вы можете интегрировать её в проект с помощью Redoc без лишних хлопот.
Простая навигация. В отличие от Swagger UI, который иногда может быть перегруженным, Redoc предлагает боковое навигационное меню, которое делает доступ к эндпоинтам более удобным.
Уникальные возможности
- Поддержка Markdown внутри описаний.
- Поддержка сложных структур данных (например, вложенных объектов).
- Возможность настройки внешнего вида и добавления кастомного брендинга.
Оптимизация для больших API. Для проектов с большим количеством эндпоинтов Redoc оказывается более производительным и удобным в использовании.
Автономная работа. Redoc можно развернуть как статическую HTML-страницу, что позволяет использовать документацию без необходимости запуска сервера.
Спецификации OpenAPI и Redoc
Как и Swagger, Redoc работает с документацией, построенной на стандартах OpenAPI. Напомним, что OpenAPI-спецификация описывает ваше API в понятной и удобной для машин структуре. Этот файл содержит всю информацию о вашем API, включая эндпоинты, типы запросов, параметры, схемы данных, авторизацию и т.д.
Пример спецификации OpenAPI
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/api/items:
get:
summary: Get items
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: string
Redoc использует такой файл для рендеринга документации в удобном виде.
Уникальные возможности Redoc
Давайте чуть подробнее разберем, что именно делает Redoc таким привлекательным инструментом:
Боковая панель навигации. Redoc автоматически генерирует меню слева, где находятся ссылки на все эндпоинты. Это упрощает перемещение по документации, особенно в больших API.
Поддержка *Markdown.* Описания и примеры в спецификации OpenAPI можно оформлять с использованием Markdown. А Markdown — это наш любимый инструмент для создания читабельного и привлекательного текста.
Пример:
summary: "Получение списка элементов"
description: |
Здесь вы можете запросить список всех **элементов**. Данные возвращаются в формате JSON.
Режим предпросмотра объектов. Если в вашем API используются сложные схемы с вложенными объектами, Redoc может отображать их в компактном виде с разворачивающимися деталями.
Поддержка кастомизации.
- Вы можете добавить логотип вашей компании.
- Настроить цветовую схему.
- Включить или отключить определенные части документации.
Почему Redoc?
Преимущества использования Redoc в вашем проекте становятся очевидными, если:
- Вы хотите предоставить своим пользователям (или разработчикам) чистую, современную и простую документацию.
- Вас раздражает недостаток кастомизации в Swagger UI.
- Вы делаете упор на восприятие вашей документации клиентами.
- Вам нужно интегрировать документацию в виде статической HTML-страницы.
Хотя Swagger UI более распространен и, вероятно, лучше поддерживается сообществом, Redoc становится предпочтительным выбором для проектов, где важна презентабельность.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ