REST-фреймворк Django 3.6¶
Релиз 3.6 добавляет две важные новые функции в REST-фреймворк.
Встроенная интерактивная поддержка документации API.
Новая клиентская библиотека JavaScript.
Вверху: Интерактивная документация API.
Финансирование¶
Выпуск 3.6 был бы невозможен без нашего <<0 >>> в проект, и нашего <<1 >>>.
Если вы используете REST framework в коммерческих целях и хотите, чтобы эта работа продолжалась, мы настоятельно рекомендуем вам инвестировать в ее дальнейшее развитие путем ** `signing up for a paid plan <funding>`_** **.
- :raw-html-m2r:`<ul class=»premium-promo promo»>
<li><a href=»https://www.rover.com/careers/» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/rover_130x130.png)»>Rover.com</a></li> <li><a href=»https://sentry.io/welcome/» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)»>Sentry</a></li> <li><a href=»https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130. png)»>Stream</a></li> <li><a href=»https://machinalis.com/» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/Machinalis130.png)»>Machinalis</a></li> <li><a href=»https://rollbar.com» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/rollbar.png)»>Rollbar</a></li> <li><a href=»https://micropyramid.com/django-rest-framework-development-services/» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/mp-text-logo.png)»>MicroPyramid</a></li> <li><a href=»https://micropyramid.com/django-rest-framework-development-services/» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/mp-text-logo.png)»>MicroPyramid</a></li>.
</ul>`
Большое спасибо всем нашим :doc:`sponsors <https://fund.django-rest-framework.org/topics/funding/#our-sponsors>`*, и в особенности нашим премиум бэкерам, Rover.*.
Интерактивная документация по API¶
Новая документация по API REST framework поддерживает ряд особенностей:
Живое взаимодействие с API.
Поддержка различных схем аутентификации.
Фрагменты кода для клиентов Python, JavaScript и командной строки.
Библиотека coreapi требуется в качестве зависимости для документации API. Убедитесь, что установлена последняя версия (2.3.0 или выше). Библиотеки pygments и markdown являются необязательными, но рекомендуемыми.
Чтобы установить документацию API, вам нужно включить ее в URLconf вашего проекта:
from rest_framework.documentation import include_docs_urls
API_TITLE = 'API title'
API_DESCRIPTION = '...'
urlpatterns = [
...
path('docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION))
]
После установки вы должны увидеть что-то похожее на это:
В ближайшие недели мы, вероятно, внесем дополнительные уточнения в документацию API. Помните, что это новая функция, и, пожалуйста, сообщите нам, если вы столкнетесь с какими-либо проблемами или ограничениями.
Для получения дополнительной информации о документировании конечных точек API смотрите раздел «Documenting your API».
Клиентская библиотека JavaScript¶
Клиентская библиотека JavaScript позволяет загрузить схему API, а затем взаимодействовать с этим API на интерфейсе прикладного уровня, а не создавать запросы на выборку в явном виде.
Вот краткий пример, который это демонстрирует:
Загрузка клиентской библиотеки и схемы.
Создание аутентифицированного клиента.
Выполнение запроса API с помощью клиента.
index.html
<html>
<head>
<script src="/static/rest_framework/js/coreapi-0.1.0.js"></script>
<script src="/docs/schema.js"></script>
<script>
const coreapi = window.coreapi
const schema = window.schema
// Instantiate a client...
let auth = coreapi.auth.TokenAuthentication({scheme: 'JWT', token: 'xxx'})
let client = coreapi.Client({auth: auth})
// Make an API request...
client.action(schema, ['projects', 'list']).then(function(result) {
alert(result)
})
</script>
</head>
</html>
Клиентская библиотека JavaScript поддерживает различные схемы аутентификации и может использоваться как самим проектом, так и внешним клиентом, взаимодействующим с вашим API.
Клиент не ограничен использованием с фреймворковыми API REST, хотя в настоящее время он поддерживает только загрузку схем API CoreJSON. Поддержка Swagger и других схем API планируется.
Более подробную информацию см. в JavaScript client library documentation.
Классы аутентификации для клиентской библиотеки Python¶
Предыдущая поддержка аутентификации в клиентской библиотеке Python ограничивалась тем, что позволяла пользователям предоставлять явные значения заголовков.
Теперь у нас есть лучшая поддержка для обработки деталей аутентификации, с введением схем BasicAuthentication , TokenAuthentication , и SessionAuthentication.
Вы можете включить схему аутентификации при создании нового клиента.
auth = coreapi.auth.TokenAuthentication(scheme='JWT', token='xxx-xxx-xxx')
client = coreapi.Client(auth=auth)
Для получения дополнительной информации см. раздел Python client library documentation.
Амортизация¶
Обновление coreapi¶
Если вы используете генерацию схем REST framework или хотите использовать документацию API, то вам необходимо обновить coreapi до последней версии. (2.3.0)
Генерация схем из маршрутизатора¶
Аргументы маршрутизатора для генерации представления схемы, такие как schema_title , schema_url и schema_renderers , в версии 3.5 «ожидающие устаревания», теперь переведены в категорию предупреждений «устаревшие».
Вместо того, чтобы использовать DefaultRouter(schema_title='Example API') , вы должны использовать функцию get_schema_view(), и включить представление явно в ваш URL conf.
DjangoFilterBackend¶
Предупреждение 3.5 «ожидает устаревания» для встроенного DjangoFilterBackend теперь переведено в разряд «устаревших».
Вы должны изменить настройки импорта и фильтра фреймворка REST следующим образом:
rest_framework.filters.DjangoFilterBackendстановитсяdjango_filters.rest_framework.DjangoFilterBackend.rest_framework.filters.FilterSetстановитсяdjango_filters.rest_framework.FilterSet.
Что дальше¶
В ближайшие недели, вероятно, будет внесен ряд уточнений в документацию API и клиентскую библиотеку JavaScript, которые могут включать в себя следующее:
Поддержка приватных API-документов, требующих входа в систему.
Поддержка загрузки и выгрузки файлов в документации по JavaScript-клиенту и API.
Исчерпывающая документация по клиентской библиотеке JavaScript.
Автоматическое включение деталей аутентификации в сниппеты кода API doc.
Добавление поддержки аутентификации в клиенте командной строки.
Поддержка загрузки Swagger и других схем в JavaScript-клиенте.
Улучшена поддержка документирования схем параметров и схем ответов.
Доработка модального взаимодействия документации API.
Как только работа над этими доработками будет завершена, мы начнем работу над поддержкой реального времени в релизе 3.7.