Вступ до Redoc та його переваги

Як ти вже напевно помітив, світ API не терпить хаосу, і потреба в структурованій та деталізованій документації API виходить на перший план. Ми вже познайомилися з таким інструментом документування, як Swagger, і тепер час вивчити його головного конкурента — Redoc. Чим відрізняється цей інструмент, які в нього переваги та як його використовувати в проєкті? Час розбиратися!

Що таке Redoc?

Redoc — це інструмент для документування API, який використовує специфікацію OpenAPI (раніше відому як Swagger Specification). Він надає зручний та сучасний інтерфейс для перегляду API-документації та фокусується на зручності сприйняття для розробників.

Переваги Redoc

1. Інтерфейс Redoc виглядає дуже свіжо, мінімалістично та професійно. Якщо Swagger UI нагадує дошку оголошень з купою кнопок, то Redoc пропонує плавні переходи та структуроване представлення даних.

2. Підтримка специфікацій OpenAPI. Redoc підтримує специфікації OpenAPI версій 2.0 та 3.0. Це означає, що якщо у вас вже є специфікація у форматі OpenAPI, ви можете інтегрувати її в проєкт за допомогою Redoc без зайвих клопотів.

3. Проста навігація. На відміну від Swagger UI, який іноді може бути перевантаженим, Redoc пропонує бокове навігаційне меню, що робить доступ до ендпоінтів більш зручним.

4. Унікальні можливості

   • Підтримка Markdown всередині описів.
   • Підтримка складних структур даних (наприклад, вкладених об'єктів).
   • Можливість налаштування зовнішнього вигляду та додавання кастомного брендингу.

5. Оптимізація для великих API. Для проєктів з великою кількістю ендпоінтів Redoc виявляється більш продуктивним та зручним у використанні.

6. Автономна робота. 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: Отримати елементи
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Redoc використовує такий файл для рендерингу документації у зручному вигляді.

Унікальні можливості Redoc

Давайте трохи детальніше розберемо, що саме робить Redoc таким привабливим інструментом:

1. Бічна панель навігації. Redoc автоматично генерує меню зліва, де знаходяться посилання на всі ендпоінти. Це спрощує переміщення по документації, особливо у великих API.

2. Підтримка *Markdown.* Описання та приклади у специфікації OpenAPI можна оформлювати з використанням Markdown. А Markdown — це наш улюблений інструмент для створення читабельного та привабливого тексту.

Приклад:

summary: "Отримання списку елементів"
description: |
  Тут ви можете запитати список усіх **елементів**. Дані повертаються у форматі JSON.

3. Режим попереднього перегляду об'єктів. Якщо у вашому API використовуються складні схеми з вкладеними об'єктами, Redoc може відображати їх у компактному вигляді з розгортанням деталей.

4. Підтримка кастомізації.

   • Ви можете додати логотип вашої компанії.
   • Налаштувати кольорову схему.
   • Увімкнути або вимкнути певні частини документації.

Чому Redoc?

Переваги використання Redoc у вашому проєкті стають очевидними, якщо:

• Ви хочете надати своїм користувачам (або розробникам) чисту, сучасну та просту документацію.
• Вас дратує брак кастомізації в Swagger UI.
• Ви робите акцент на сприйняття вашої документації клієнтами.
• Вам потрібно інтегрувати документацію у вигляді статичної HTML-сторінки.

Хоча Swagger UI більш поширений і, ймовірно, краще підтримується спільнотою, Redoc стає переважним вибором для проєктів, де важлива презентабельність.