> For the complete documentation index, see [llms.txt](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/browsable-api.md).

# The Browsable API

> Это глубоко ошибочный трюизм... что мы должны культивировать привычку думать о том, что мы делаем. Все обстоит с точностью до наоборот. Цивилизация развивается за счет увеличения числа важных операций, которые мы можем выполнять, не задумываясь о них.
>
> — [Альфред Норт Уайтхед](https://en.wikiquote.org/wiki/Alfred_North_Whitehead), Введение в математику (1911)

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

## URLs

Если вы включите в вывод ресурсов полностью определенные URL, они будут "урлизованы" и сделаны кликабельными для удобства просмотра человеком. Для этого в пакет `rest_framework` включен помощник [`reverse`](/django-rest-framework-russian-documentation/overview/navigaciya-po-api/reverse.md).

## Форматы

По умолчанию API возвращает формат, указанный в заголовках, который в случае браузера является HTML. Формат может быть указан с помощью `?format=` в запросе, так что вы можете просмотреть необработанный JSON-ответ в браузере, добавив `?format=json` к URL. Существуют полезные расширения для просмотра JSON в [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jsonview/) и [Chrome](https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc).

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

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

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

## Настройка

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

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

**templates/rest\_framework/api.html**

```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. Это полностью заменит включенную тему.

```html

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

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

</div>

```

Подходящие готовые темы для замены доступны на сайте [Bootswatch](https://bootswatch.com/). Чтобы использовать любую из тем Bootswatch, просто скачайте файл `bootstrap.min.css` этой темы, добавьте его в свой проект и замените тему по умолчанию, как описано выше. Убедитесь, что версия Bootstrap новой темы совпадает с версией темы по умолчанию.

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

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

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

```html

<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 theme](https://github.com/encode/django-rest-framework/raw/master/docs/img/cerulean.png)

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

***

![Slate theme](https://github.com/encode/django-rest-framework/raw/master/docs/img/slate.png)

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

***

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

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

* [rest-framework-redesign](https://github.com/youzarsiph/rest-framework-redesign) - Пакет для настройки API с помощью Bootstrap 5. Современный и элегантный дизайн, поддержка темного режима.
* [rest-framework-material](https://github.com/youzarsiph/rest-framework-material) - Материальный дизайн для Django REST Framework.

***

![Django REST Framework Redesign](https://github.com/encode/django-rest-framework/raw/master/docs/img/rfr.png)

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

***

![Django REST Framework Material](https://github.com/encode/django-rest-framework/raw/master/docs/img/rfm.png)

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

***

### Блоки

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

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

#### Компоненты

Доступны все стандартные [Bootstrap-компоненты](https://getbootstrap.com/2.3.2/components.html).

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

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

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

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

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

```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 на стандартный текстовый виджет. Например:

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

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

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

Существует [множество пакетов для виджетов автозаполнения](https://www.djangopackages.com/grids/g/auto-complete/), например [django-autocomplete-light](https://github.com/yourlabs/django-autocomplete-light), к которым вы можете обратиться. Обратите внимание, что вы не сможете просто включить эти компоненты в качестве стандартных виджетов, а должны будете явно написать HTML-шаблон. Это связано с тем, что REST framework 3.0 больше не поддерживает именованный аргумент `widget`, так как теперь он использует шаблонизацию HTML.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/browsable-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.