The Browsable API
Last updated
Was this helpful?
Last updated
Was this helpful?
Это глубоко ошибочный трюизм... что мы должны культивировать привычку думать о том, что мы делаем. Все обстоит с точностью до наоборот. Цивилизация развивается за счет увеличения числа важных операций, которые мы можем выполнять, не задумываясь о них.
— , Введение в математику (1911)
API может означать интерфейс прикладного программирования(Application Programming Interface), но люди тоже должны уметь читать API; кто-то должен заниматься программированием. DRF поддерживает генерацию удобного для человека HTML-вывода для каждого ресурса при запросе формата HTML. Эти страницы позволяют легко просматривать ресурсы, а также содержат формы для отправки данных на ресурсы с помощью POST, PUT и DELETE.
Если вы включите в вывод ресурсов полностью определенные URL, они будут "урлизованы" и сделаны кликабельными для удобства просмотра человеком. Для этого в пакет rest_framework включен помощник .
По умолчанию API возвращает формат, указанный в заголовках, который в случае браузера является HTML. Формат может быть указан с помощью ?format= в запросе, так что вы можете просмотреть необработанный JSON-ответ в браузере, добавив ?format=json к URL. Существуют полезные расширения для просмотра JSON в и .
Чтобы быстро добавить аутентификацию в Web-интерфейсе API, добавьте маршруты с именами "login" и "logout" в пространстве имен "rest_framework". DRF предоставляет для этого маршруты по умолчанию, которые вы можете добавить в свой urlconf:
Чтобы настроить стиль по умолчанию, создайте шаблон rest_framework/api.html, который расширяет rest_framework/base.html. Например:
templates/rest_framework/api.html
Чтобы заменить тему по умолчанию, добавьте блок bootstrap_theme в ваш api.html и вставьте ссылку на нужный css-файл темы Bootstrap. Это полностью заменит включенную тему.
Вы также можете изменить вариант навигационной панели, которая по умолчанию имеет значение navbar-inverse, с помощью блока bootstrap_navbar_variant. Пустой блок `
` будет использовать оригинальный стиль навигационной панели Bootstrap.
Полный пример:
Для более специфических CSS-настроек, чем просто переопределение темы bootstrap по умолчанию, вы можете переопределить блок style.
Скриншот темы "Cerulean"
Скриншот темы "Slate"
Вы можете использовать сторонние пакеты для кастомизации, а не делать это самостоятельно. Вот 2 пакета для настройки API:
Скриншот темы rest-framework-redesign
Скриншот темы rest-framework-material
Все блоки, доступные в базовом шаблоне Web-интерфейса API, которые можно использовать в вашем api.html.
body - Весь html-тег <body>.
bodyclass - Атрибут класса для тега <body>, по умолчанию пустой.
bootstrap_theme - CSS для темы Bootstrap.
bootstrap_navbar_variant - CSS-класс для навигационной панели.
breadcrumbs - Ссылки, показывающие вложенность ресурсов, позволяющие пользователю вернуться к ним. Рекомендуется сохранять их, но их можно переопределить с помощью блока breadcrumbs.
script - Файлы JavaScript для страницы.
style - Таблицы стилей CSS для страницы.
title - Заголовок страницы.
userlinks - Список ссылок справа от заголовка, по умолчанию содержит ссылки на вход/выход. Чтобы добавить ссылки вместо замены, используйте {{ block.super }}, чтобы сохранить ссылки аутентификации.
Web-интерфейс API использует компонент Bootstrap tooltips. Любой элемент с классом js-tooltip и атрибутом title имеет содержание заголовка, который будет отображать всплывающую подсказку при наведении.
Чтобы добавить брендинг и настроить внешний вид шаблона входа в систему, создайте шаблон login.html и добавьте его в свой проект, например: templates/rest_framework/login.html. Шаблон должен расширяться от rest_framework/login_base.html.
Вы можете добавить название своего сайта или брендинг, включив блок брендинга:
Вы также можете настроить стиль, добавив блок 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(), чтобы настроить контекст, передаваемый в шаблон.
Для более продвинутой настройки, например, без основы Bootstrap или более тесной интеграции с остальным сайтом, вы можете просто убрать в api.html расширение base.html. Тогда содержание и возможности страницы будут зависеть только от вас.
ChoiceField с большим количеством элементов.Когда в отношениях или ChoiceField слишком много элементов, рендеринг виджета, содержащего все варианты, может стать очень медленным, что приведет к плохой работе рендеринга Web-интерфейса API.
Самый простой вариант в этом случае - заменить виджет select на стандартный текстовый виджет. Например:
Альтернативным, но более сложным вариантом будет замена виджета ввода виджетом автозаполнения, который будет загружать и отображать только подмножество доступных вариантов по мере необходимости. Если вам нужно сделать это, вам придется потрудиться, чтобы создать собственный HTML-шаблон автозаполнения.
Web-интерфейс API построен с использованием (v 3.4.1), что позволяет легко настроить внешний вид и функциональность.
Подходящие готовые темы для замены доступны на сайте . Чтобы использовать любую из тем Bootswatch, просто скачайте файл bootstrap.min.css этой темы, добавьте его в свой проект и замените тему по умолчанию, как описано выше. Убедитесь, что версия Bootstrap новой темы совпадает с версией темы по умолчанию.
- Пакет для настройки API с помощью Bootstrap 5. Современный и элегантный дизайн, поддержка темного режима.
- Материальный дизайн для Django REST Framework.
branding - Раздел брендирования navbar, см. .
Доступны все стандартные .
Существует , например , к которым вы можете обратиться. Обратите внимание, что вы не сможете просто включить эти компоненты в качестве стандартных виджетов, а должны будете явно написать HTML-шаблон. Это связано с тем, что REST framework 3.0 больше не поддерживает именованный аргумент widget, так как теперь он использует шаблонизацию HTML.
