REST-фреймворк Django 3.9

Релиз 3.9 предоставляет доступ к дополнительным действиям в Browsable API, вводит составные разрешения и встроенную поддержку схемы OpenAPI. (Ранее известный как Swagger)


Финансирование

Если вы используете REST framework в коммерческих целях и хотите, чтобы эта работа продолжалась, мы настоятельно рекомендуем вам инвестировать в ее дальнейшее развитие путем ** `signing up for a paid&nbsp;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://auklet.io» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/auklet-new. png)»>Auklet</a></li> <li><a href=»https://rollbar.com» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/rollbar2.png)»>Rollbar</a></li> <li><a href=»https://cadre.com» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/cadre.png)»>Cadre</a></li> <li><a href=»https://loadimpact. com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/load-impact.png)»>Load Impact</a></li> <li><a href=»https://hubs.ly/H0f30Lf0» style=»background-image: url(https://fund-rest-framework.s3.amazonaws.com/kloudless.png)»>Kloudless</a></li>

</ul>`

Большое спасибо всем нашим :doc:`wonderful sponsors <https://fund.django-rest-framework.org/topics/funding/#our-sponsors>`*, и в особенности нашим премиум бэкерам, Rover.*.


Встроенная поддержка схем OpenAPI

REST-фреймворк теперь имеет первую попытку прямого включения поддержки схем OpenAPI. (Ранее известный как Swagger)

В частности:

  • Теперь есть OpenAPIRenderer , и JSONOpenAPIRenderer классы, которые занимаются кодированием coreapi.Document экземпляров в OpenAPI YAML или OpenAPI JSON.

  • Метод get_schema_view(...) теперь по умолчанию использует OpenAPI YAML, с CoreJSON в качестве вторичного варианта, если он выбран через согласование содержимого HTTP.

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

Вот пример добавления схемы OpenAPI в URL conf:

from rest_framework.schemas import get_schema_view
from rest_framework.renderers import JSONOpenAPIRenderer
from django.urls import path

schema_view = get_schema_view(
    title='Server Monitoring API',
    url='https://www.example.org/api/',
    renderer_classes=[JSONOpenAPIRenderer]
)

urlpatterns = [
    path('schema.json', schema_view),
    ...
]

А вот как можно использовать команду управления generateschema:

$ python manage.py generateschema --format openapi > schema.yml

Существует множество различных инструментов, которые вы можете использовать для работы со схемами OpenAPI. Одним из вариантов, над которым мы работаем, является инструмент командной строки API Star.

Вы можете использовать apistar для проверки схемы вашего API:

$ apistar validate --path schema.json --format openapi
✓ Valid OpenAPI schema.

Или для создания документации по API:

$ apistar docs --path schema.json --format openapi
✓ Documentation built at "build/index.html".

API Star также включает dynamic client library, который использует схему API для автоматического предоставления интерфейса клиентской библиотеки для выполнения запросов.

Составляемые классы разрешений

Теперь вы можете составлять классы разрешений, используя операторы и/или, & и |.

Например…

permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)]

Если вы используете пользовательские классы разрешений, убедитесь, что вы используете подклассы из BasePermission, чтобы включить эту поддержку.

ViewSet Дополнительные действия, доступные в Browsable API

После введения декоратора action в v3.8, дополнительные действия, определенные на ViewSet, теперь доступны из Browsable API.

Extra Actions displayed in the Browsable API

При определении отображается выпадающий список «Дополнительные действия», соответствующим образом отфильтрованный на подробные/неподробные действия.


Поддерживаемые версии

REST framework 3.9 поддерживает Django версий 1.11, 2.0 и 2.1.


Амортизация

DjangoObjectPermissionsFilter перемещен в сторонний пакет.

Класс DjangoObjectPermissionsFilter находится в процессе депривации, будет деприватизирован в 3.10 и полностью удален в 3.11.

Он был перемещен в сторонний пакет ** ``djangorestframework-guardian:doc:` <https://github.com/rpkilby/django-rest-framework-guardian>`. Пожалуйста, используйте его вместо этого.

Аргумент/метод маршрутизатора переименован, чтобы использовать basename для согласованности.

  • Аргумент Router.register base_name был переименован в пользу basename.

  • Метод Router.get_default_base_name был переименован в пользу Router.get_default_basename. #5990

См. #5990.

base_name и get_default_base_name() находятся в процессе депривации. Они будут устаревшими в версии 3.10 и полностью удалены в версии 3.11.

Декоратор action заменяет list_route и detail_route

Декораторы list_route и detail_route теперь устарели в пользу единственного декоратора action. Они будут полностью удалены в версии 3.10.

Декоратор action принимает булевый аргумент detail.

  • Замените использование detail_route на @action(detail=True).

  • Замените использование list_route на @action(detail=False).

exclude_from_schema

Оба аргумента APIView.exclude_from_schema и exclude_from_schema для @api_view теперь удалены.

Для APIView следует вместо этого установить атрибут schema = None в классе представления.

Для представлений на основе функций декоратор @schema можно использовать для исключения представления из схемы, используя @schema(None).


Мелкие исправления и улучшения

В этом выпуске содержится большое количество мелких исправлений и улучшений. Полный список смотрите на странице release notes.

Что дальше

Мы планируем итеративно работать над тем, чтобы OpenAPI стал стандартным представлением схемы. Это будет означать, что зависимость coreapi будет постепенно удаляться, и мы будем генерировать схему напрямую, а не создавать объект CoreAPI Document.

OpenAPI явно стал стандартом для спецификации веб-интерфейсов API, поэтому наша модель документов, не зависящая от схемы, больше не представляет особой ценности. Это изменение означает, что нам будет легче воспользоваться всеми возможностями OpenAPI.

Это также позволит расширить ассортимент оснастки.

Мы сосредоточимся на продолжении развития библиотеки API Star и клиентского инструмента в рекомендуемый вариант для создания документации API, проверки схем API и предоставления динамической клиентской библиотеки.

Кроме того, ведется огромная работа по совершенствованию ASGI-ландшафта, и есть вероятность, что некоторые из этих работ в конечном итоге feed back into Django.

Будет продолжена работа над веб-сервером Uvicorn, а также планируется много функциональности для веб-фреймворка Starlette, который создает фундаментальный набор инструментов для работы с ASGI.

Вернуться на верх