Django REST framework 3.9
The 3.9 release gives access to extra actions in the Browsable API, introduces composable permissions and built-in OpenAPI schema support. (Formerly known as Swagger)
Funding
If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by signing up for a paid plan.
Many thanks to all our wonderful sponsors, and in particular to our premium backers, Rover, Sentry, Stream, Auklet, Rollbar, Cadre, Load Impact, and Kloudless.
Built-in OpenAPI schema support
REST framework now has a first-pass at directly including OpenAPI schema support. (Formerly known as Swagger)
Specifically:
- There are now
OpenAPIRenderer
, andJSONOpenAPIRenderer
classes that deal with encodingcoreapi.Document
instances into OpenAPI YAML or OpenAPI JSON. - The
get_schema_view(...)
method now defaults to OpenAPI YAML, with CoreJSON as a secondary option if it is selected via HTTP content negotiation. - There is a new management command
generateschema
, which you can use to dump the schema into your repository.
Here's an example of adding an OpenAPI schema to the 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), ...]
And here's how you can use the generateschema
management command:
$ python manage.py generateschema --format openapi > schema.yml
There's lots of different tooling that you can use for working with OpenAPI schemas. One option that we're working on is the API Star command line tool.
You can use apistar
to validate your API schema:
$ apistar validate --path schema.json --format openapi
✓ Valid OpenAPI schema.
Or to build API documentation:
$ apistar docs --path schema.json --format openapi
✓ Documentation built at "build/index.html".
API Star also includes a dynamic client library that uses an API schema to automatically provide a client library interface for making requests.
Composable permission classes
You can now compose permission classes using the and/or operators, &
and |
.
For example...
permission_classes = [IsAuthenticated & (ReadOnly | IsAdminUser)]
If you're using custom permission classes then make sure that you are subclassing
from BasePermission
in order to enable this support.
ViewSet Extra Actions available in the Browsable API
Following the introduction of the action
decorator in v3.8, extra actions defined on a ViewSet are now available
from the Browsable API.
When defined, a dropdown of "Extra Actions", appropriately filtered to detail/non-detail actions, is displayed.
Supported Versions
REST framework 3.9 supports Django versions 1.11, 2.0, and 2.1.
Deprecations
DjangoObjectPermissionsFilter
moved to third-party package.
The DjangoObjectPermissionsFilter
class is pending deprecation, will be deprecated in 3.10 and removed entirely in 3.11.
It has been moved to the third-party djangorestframework-guardian
package. Please use this instead.
Router argument/method renamed to use basename
for consistency.
- The
Router.register
base_name
argument has been renamed in favor ofbasename
. - The
Router.get_default_base_name
method has been renamed in favor ofRouter.get_default_basename
. #5990
See #5990.
base_name
and get_default_base_name()
are pending deprecation. They will be deprecated in 3.10 and removed entirely in 3.11.
action
decorator replaces list_route
and detail_route
Both list_route
and detail_route
are now deprecated in favour of the single action
decorator.
They will be removed entirely in 3.10.
The action
decorator takes a boolean detail
argument.
- Replace
detail_route
uses with@action(detail=True)
. - Replace
list_route
uses with@action(detail=False)
.
exclude_from_schema
Both APIView.exclude_from_schema
and the exclude_from_schema
argument to the @api_view
have now been removed.
For APIView
you should instead set a schema = None
attribute on the view class.
For function-based views the @schema
decorator can be used to exclude the view from the schema, by using @schema(None)
.
Minor fixes and improvements
There are a large number of minor fixes and improvements in this release. See the release notes page for a complete listing.
What's next
We're planning to iteratively work towards OpenAPI becoming the standard schema
representation. This will mean that the coreapi
dependency will gradually become
removed, and we'll instead generate the schema directly, rather than building
a CoreAPI Document
object.
OpenAPI has clearly become the standard for specifying Web APIs, so there's not much value any more in our schema-agnostic document model. Making this change will mean that we'll more easily be able to take advantage of the full set of OpenAPI functionality.
This will also make a wider range of tooling available.
We'll focus on continuing to develop the API Star library and client tool into a recommended option for generating API docs, validating API schemas, and providing a dynamic client library.
There's also a huge amount of ongoing work on maturing the ASGI landscape, with the possibility that some of this work will eventually feed back into Django.
There will be further work on the Uvicorn web server, as well as lots of functionality planned for the Starlette web framework, which is building a foundational set of tooling for working with ASGI.