Налаштування Redoc для проєкту

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

швидким завантаженням і зручним для сприйняття "односторінковим" форматом.

Встановлення та базове налаштування Redoc

1. Встановлення Redoc

Redoc не потрібно завантажувати окремо, він вбудований у ваш проєкт за допомогою специфікації OpenAPI. Однак ми підключимо його до нашого застосунку, щоб Redoc міг рендерити документацію.

Додайте бібліотеку drf-yasg (якщо ви ще цього не зробили):

pip install drf-yasg

Документацію для Redoc ми будемо створювати саме за допомогою drf-yasg. Не хвилюйтесь: це не складно, і ви скоро побачите результат.

2. Налаштування базового ендпоінту для Redoc

У кореневому urls.py проєкту, де ви вже налаштували маршрути для вашого API, додамо новий маршрут для Redoc. Ось як це виглядає:

from django.urls import path
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# Створюємо об'єкт schema_view
schema_view = get_schema_view(
    openapi.Info(
        title="Ваш API",
        default_version="v1",
        description="Документація для API з використанням Redoc",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="support@example.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
)

urlpatterns = [
    # Маршрут для документації Redoc
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

Тепер ви можете відкрити вашу документацію, відвідавши URL: http://127.0.0.1:8000/redoc/. Це буде сторінка Redoc, автоматично згенерована на основі всіх ваших поточних ендпоінтів.

Інтеграція Redoc у проєкт

Щоб Redoc став не просто інструментом, а повноцінною частиною вашого проєкту, потрібно подбати про кілька аспектів: доступність, зручність використання та актуальність документації.

1. Покращення доступності

Redoc виглядає привабливо, якщо його розмістити в основному шаблоні вашого сайту. Наприклад, це може бути доступне меню або розділ "Документація" у заголовку сайту.

Створіть посилання на документацію в основному шаблоні HTML (наприклад, base.html):

<nav>
    <ul<>
        <li><a href="{% url 'schema-redoc' %}"<Документація API</a></li>
    </ul>
</nav>

Це посилання буде вести користувачів прямо на сторінку Redoc, роблячи її частиною основного інтерфейсу вашого додатка.

2. Зміна опису проєкту в документації

Зверніть увагу, що опис і назва вашого API в документації вказуються в блоці openapi.Info. Щоб додати більше корисної інформації, змініть текст наступним чином:

schema_view = get_schema_view(
    openapi.Info(
        title="Мій крутий API",  # Назва API
        default_version="v1",  # Версія API
        description="""Ласкаво просимо до документації API! 
        Тут ви знайдете опис усіх доступних ендпоінтів і приклади запиту даних.""",
        terms_of_service="https://example.com/terms/",
        contact=openapi.Contact(email="admin@example.com"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
)

Тепер ваш Redoc виглядатиме ще професійніше та дружелюбніше.

Додаткові налаштування Redoc

1. Налаштування стилів

Хочеш додати логотип або змінити кольори? На жаль, кастомізація зовнішнього вигляду в Redoc трохи обмежена. Проте ти можеш використовувати CSS та JavaScript для тонкого налаштування інтерфейсу.

Додай HTML-елемент з логотипом у свій базовий шаблон (разом з iframe для Redoc):

<div>
    <img src="https://example.com/logo.png" alt="Логотип" />
    <iframe src="{% url 'schema-redoc' %}" width="100%" height="700"></iframe>
</div>

Для більш складної кастомізації варто використовувати форк проєкту Redoc або передавати кастомні специфікації OpenAPI.

2. Робота з кількома версіями API

Якщо у тебе кілька версій API, то це не проблема — Redoc підтримує їх відображення! Налаштуй schema_view для кожної версії.

Приклад з версією v2:

schema_view_v2 = get_schema_view(
    openapi.Info(
        title="Мій крутий API",
        default_version="v2",
        description="Документація для API версії 2.0",
        terms_of_service="https://example.com/terms/",
        contact=openapi.Contact(email="admin@example.com"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
)

urlpatterns = [
    path('redoc/v2/', schema_view_v2.with_ui('redoc', cache_timeout=0), name='schema-redoc-v2'),
]

Тепер користувачі зможуть бачити, яка версія API доступна для використання.

Перевіряємо роботу Redoc

Щоб переконатися, що все працює правильно, ось чек-лист:

1. Перейдіть на URL http://127.0.0.1:8000/redoc/ і перевірте, чи відображаються ваші ендпоінти.
2. Переконайтеся, що інформація (назва, опис, ліцензія) відповідає очікуваному.
3. Відкрийте кілька ендпоінтів і перевірте, чи є деталі по запитах (методи, параметри та тіло запиту).

Якщо щось пішло не так, перевірте налаштування у urls.py та коректність вказаних даних у OpenAPI. Також ви можете зазирнути в офіційну документацію Redoc.

Практичні завдання

Завдання 1: додайте Redoc у ваш проєкт

• Налаштуйте маршрут для Redoc.
• Змініть назву та опис API.
• Перевірте доступність документації через браузер.

Завдання 2: налаштування кількох версій API

• Додайте кілька маршрутів у urls.py для різних версій API.
• Перевірте, що кожна версія відображається коректно.

Завдання 3: кастомізуйте документацію

• Додайте логотип на початок документації.
• Спробуйте змінити опис ендпоінтів, використовуючи анотації @swagger_auto_schema.