The Browsable API

Это глубоко ошибочный трюизм... что мы должны культивировать привычку думать о том, что мы делаем. Все обстоит с точностью до наоборот. Цивилизация развивается за счет увеличения числа важных операций, которые мы можем выполнять, не задумываясь о них.

— Альфред Норт Уайтхед, Введение в математику (1911)

API может означать интерфейс прикладного программирования(Application Programming Interface), но люди тоже должны уметь читать API; кто-то должен заниматься программированием. DRF поддерживает генерацию удобного для человека HTML-вывода для каждого ресурса при запросе формата HTML. Эти страницы позволяют легко просматривать ресурсы, а также содержат формы для отправки данных на ресурсы с помощью POST, PUT и DELETE.

URLs

Если вы включите в вывод ресурсов полностью определенные URL, они будут "урлизованы" и сделаны кликабельными для удобства просмотра человеком. Для этого в пакет rest_framework включен помощник reverse.

Форматы

По умолчанию API возвращает формат, указанный в заголовках, который в случае браузера является HTML. Формат может быть указан с помощью ?format= в запросе, так что вы можете просмотреть необработанный JSON-ответ в браузере, добавив ?format=json к URL. Существуют полезные расширения для просмотра JSON в Firefox и Chrome.

Аутентификация

Чтобы быстро добавить аутентификацию в Web-интерфейсе API, добавьте маршруты с именами "login" и "logout" в пространстве имен "rest_framework". DRF предоставляет для этого маршруты по умолчанию, которые вы можете добавить в свой urlconf:

urlpatterns = [
    # ...
    url(r"^api-auth/", include("rest_framework.urls", namespace="rest_framework"))
]

Настройка

Web-интерфейс API построен с использованием Twitter's Bootstrap (v 3.4.1), что позволяет легко настроить внешний вид и функциональность.

Чтобы настроить стиль по умолчанию, создайте шаблон rest_framework/api.html, который расширяет rest_framework/base.html. Например:

templates/rest_framework/api.html


<div data-gb-custom-block data-tag="extends" data-0='rest_framework/base.html'></div>

...  # Override blocks with required customizations

Переопределение темы по умолчанию

Чтобы заменить тему по умолчанию, добавьте блок bootstrap_theme в ваш api.html и вставьте ссылку на нужный css-файл темы Bootstrap. Это полностью заменит включенную тему.


<div data-gb-custom-block data-tag="block">

    <link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">

</div>

Подходящие готовые темы для замены доступны на сайте Bootswatch. Чтобы использовать любую из тем Bootswatch, просто скачайте файл bootstrap.min.css этой темы, добавьте его в свой проект и замените тему по умолчанию, как описано выше. Убедитесь, что версия Bootstrap новой темы совпадает с версией темы по умолчанию.

Вы также можете изменить вариант навигационной панели, которая по умолчанию имеет значение navbar-inverse, с помощью блока bootstrap_navbar_variant. Пустой блок `

` будет использовать оригинальный стиль навигационной панели Bootstrap.

Полный пример:


<div data-gb-custom-block data-tag="extends" data-0='rest_framework/base.html'></div>

<div data-gb-custom-block data-tag="block">

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@3.4.1/flatly/bootstrap.min.css" type="text/css">

</div>

<div data-gb-custom-block data-tag="block"></div>

Для более специфических CSS-настроек, чем просто переопределение темы bootstrap по умолчанию, вы можете переопределить блок style.

Скриншот темы "Cerulean"

Скриншот темы "Slate"

Пакеты сторонних разработчиков для настройки

Вы можете использовать сторонние пакеты для кастомизации, а не делать это самостоятельно. Вот 2 пакета для настройки API:

  • rest-framework-redesign - Пакет для настройки API с помощью Bootstrap 5. Современный и элегантный дизайн, поддержка темного режима.

  • rest-framework-material - Материальный дизайн для Django REST Framework.

Скриншот темы rest-framework-redesign

Скриншот темы rest-framework-material

Блоки

Все блоки, доступные в базовом шаблоне Web-интерфейса API, которые можно использовать в вашем api.html.

  • body - Весь html-тег <body>.

  • bodyclass - Атрибут класса для тега <body>, по умолчанию пустой.

  • bootstrap_theme - CSS для темы Bootstrap.

  • bootstrap_navbar_variant - CSS-класс для навигационной панели.

  • branding - Раздел брендирования navbar, см. Bootstrap components.

  • breadcrumbs - Ссылки, показывающие вложенность ресурсов, позволяющие пользователю вернуться к ним. Рекомендуется сохранять их, но их можно переопределить с помощью блока breadcrumbs.

  • script - Файлы JavaScript для страницы.

  • style - Таблицы стилей CSS для страницы.

  • title - Заголовок страницы.

  • userlinks - Список ссылок справа от заголовка, по умолчанию содержит ссылки на вход/выход. Чтобы добавить ссылки вместо замены, используйте {{ block.super }}, чтобы сохранить ссылки аутентификации.

Компоненты

Доступны все стандартные Bootstrap-компоненты.

Всплывающие подсказки

Web-интерфейс API использует компонент Bootstrap tooltips. Любой элемент с классом js-tooltip и атрибутом title имеет содержание заголовка, который будет отображать всплывающую подсказку при наведении.

Шаблон для входа в систему

Чтобы добавить брендинг и настроить внешний вид шаблона входа в систему, создайте шаблон login.html и добавьте его в свой проект, например: templates/rest_framework/login.html. Шаблон должен расширяться от rest_framework/login_base.html.

Вы можете добавить название своего сайта или брендинг, включив блок брендинга:


<div data-gb-custom-block data-tag="extends" data-0='rest_framework/login_base.html'></div>

<div data-gb-custom-block data-tag="block">

    <h3 style="margin: 0 0 20px;">My Site Name</h3>

</div>

Вы также можете настроить стиль, добавив блок bootstrap_theme или style, аналогичный api.html.

Расширенная настройка

Контекст

Контекст, доступный шаблону:

  • allowed_methods : Список методов, разрешенных ресурсу

  • api_settings : Настройки API

  • available_formats : Список форматов, разрешенных ресурсом

  • breadcrumblist : Список ссылок, следующих по цепочке вложенных ресурсов

  • content : Содержание ответа API

  • description : Описание ресурса, сгенерированное из его docstring

  • name : Название ресурса

  • post_form : Экземпляр формы для использования POST-формой (если разрешено)

  • put_form : Экземпляр формы для использования PUT-формой (если разрешено)

  • display_edit_forms : Булево значение, указывающее, будут ли отображаться формы POST, PUT и PATCH.

  • request : Объект запроса

  • response : Объект ответа

  • version : Версия Django REST Framework

  • view : Представление, обрабатывающее запрос

  • FORMAT_PARAM : Представление может принимать переопределение формата

  • METHOD_PARAM : Представление может принимать переопределение метода

Вы можете переопределить метод BrowsableAPIRenderer.get_context(), чтобы настроить контекст, передаваемый в шаблон.

Неиспользование файла base.html

Для более продвинутой настройки, например, без основы Bootstrap или более тесной интеграции с остальным сайтом, вы можете просто убрать в api.html расширение base.html. Тогда содержание и возможности страницы будут зависеть только от вас.

Обработка ChoiceField с большим количеством элементов.

Когда в отношениях или ChoiceField слишком много элементов, рендеринг виджета, содержащего все варианты, может стать очень медленным, что приведет к плохой работе рендеринга Web-интерфейса API.

Самый простой вариант в этом случае - заменить виджет select на стандартный текстовый виджет. Например:

author = serializers.HyperlinkedRelatedField(
    queryset=User.objects.all(),
    style={'base_template': 'input.html'}
)

Автозаполнение

Альтернативным, но более сложным вариантом будет замена виджета ввода виджетом автозаполнения, который будет загружать и отображать только подмножество доступных вариантов по мере необходимости. Если вам нужно сделать это, вам придется потрудиться, чтобы создать собственный HTML-шаблон автозаполнения.

Существует множество пакетов для виджетов автозаполнения, например django-autocomplete-light, к которым вы можете обратиться. Обратите внимание, что вы не сможете просто включить эти компоненты в качестве стандартных виджетов, а должны будете явно написать HTML-шаблон. Это связано с тем, что REST framework 3.0 больше не поддерживает именованный аргумент widget, так как теперь он использует шаблонизацию HTML.

PreviousAJAX, CSRF & CORSNextУлучшения в браузере

Last updated