Настройка 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.