Skip to content

Latest commit

 

History

History
161 lines (104 loc) · 12.5 KB

browsable-api.md

File metadata and controls

161 lines (104 loc) · 12.5 KB

Browsable API

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

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

URLs

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

Форматы

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

Настройка

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

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

templates/rest_framework/api.html

{% extends "rest_framework/base.html" %}

...  # Override blocks with required customizations

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

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

{% block bootstrap_theme %}
    <link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">
{% endblock %}

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

Вы также можете изменить вариант навигационной панели, который по умолчанию является navbar-inverse, используя блок bootstrap_navbar_variant. Пустой блок {% block bootstrap_navbar_variant %}{% endblock %} будет использовать оригинальный стиль навигационной панели Bootstrap.

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

{% extends "rest_framework/base.html" %}

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

{% block bootstrap_navbar_variant %}{% endblock %}

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

Cerulean theme

Скриншот загрузочной темы "Cerulean"

Slate theme

Скриншот темы bootswatch 'Slate'.

Блоки

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

  • body - Весь html <body>.
  • bodyclass - Атрибут класса для тега <body>, по умолчанию пустой.
  • bootstrap_theme - CSS для темы Bootstrap.
  • bootstrap_navbar_variant - CSS класс для навигационной панели.
  • branding - Раздел брендинга navbar, см. Bootstrap components.
  • breadcrumbs - Ссылки, показывающие вложенность ресурсов, позволяющие пользователю вернуться назад по ресурсам. Рекомендуется сохранять их, но их можно переопределить с помощью блока хлебных крошек.
  • script - файлы JavaScript для страницы.
  • style - Таблицы стилей CSS для страницы.
  • title - Заголовок страницы.
  • userlinks - Список ссылок справа от заголовка, по умолчанию содержит ссылки для входа/выхода. Чтобы добавить ссылки вместо замены, используйте {{ block.super }}, чтобы сохранить ссылки авторизации.

Компоненты

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

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

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

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

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

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

{% extends "rest_framework/login_base.html" %}

{% block branding %}
    <h3 style="margin: 0 0 20px;">My Site Name</h3>
{% endblock %}

Вы также можете настроить стиль, добавив блок 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 : Версия DRF
  • view : Представление, обрабатывающее запрос.
  • FORMAT_PARAM : Представление может принимать переопределение формата
  • METHOD_PARAM : Представление может принимать переопределение метода

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

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

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

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

Когда отношения или ChoiceField имеют слишком много элементов, рендеринг виджета, содержащего все опции, может стать очень медленным и привести к плохой работе рендеринга 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.