e794e5e5e4
* blacken-docs: Manual fixes for command to pass without errors * blacken-docs: Adds blacken-docs step to precommit hook. * blacken-docs: Adds changes made by command itself. * blacken-docs: Modifies blacken-docs step to only process files under "docs" directory * blacken-docs: Updates pre-commit config file to exclude all directories other than "docs" to be compatible with "--all-files" flag. * blacken-docs: Adds commas at the end to make it look identical to pre-black version
6.0 KiB
Django REST framework 3.10
The 3.10 release drops support for Python 2.
- Our supported Python versions are now: 3.5, 3.6, and 3.7.
- Our supported Django versions are now: 1.11, 2.0, 2.1, and 2.2.
OpenAPI Schema Generation
Since we first introduced schema support in Django REST Framework 3.5, OpenAPI has emerged as the widely adopted standard for modeling Web APIs.
This release begins the deprecation process for the CoreAPI based schema generation, and introduces OpenAPI schema generation in its place.
Continuing to use CoreAPI
If you're currently using the CoreAPI schemas, you'll need to make sure to
update your REST framework settings to include DEFAULT_SCHEMA_CLASS explicitly.
settings.py:
REST_FRAMEWORK = {
...: ...,
"DEFAULT_SCHEMA_CLASS": "rest_framework.schemas.coreapi.AutoSchema",
}
You'll still be able to keep using CoreAPI schemas, API docs, and client for the foreseeable future. We'll aim to ensure that the CoreAPI schema generator remains available as a third party package, even once it has eventually been removed from REST framework, scheduled for version 3.12.
We have removed the old documentation for the CoreAPI based schema generation. You may view the Legacy CoreAPI documentation here.
OpenAPI Quickstart
You can generate a static OpenAPI schema, using the generateschema management
command.
Alternately, to have the project serve an API schema, use the get_schema_view()
shortcut.
In your urls.py:
from rest_framework.schemas import get_schema_view
urlpatterns = [
# ...
# Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
# * `title` and `description` parameters are passed to `SchemaGenerator`.
# * Provide view name for use with `reverse()`.
path(
"openapi",
get_schema_view(title="Your Project", description="API for all things …"),
name="openapi-schema",
),
# ...
]
Customization
For customizations that you want to apply across the entire API, you can subclass rest_framework.schemas.openapi.SchemaGenerator and provide it as an argument
to the generateschema command or get_schema_view() helper function.
For specific per-view customizations, you can subclass AutoSchema,
making sure to set schema = <YourCustomClass> on the view.
For more details, see the API Schema documentation.
API Documentation
There are some great third party options for documenting your API, based on the OpenAPI schema.
See the Documenting you API section for more details.
Feature Roadmap
Given that our OpenAPI schema generation is a new feature, it's likely that there will still be some iterative improvements for us to make. There will be two main cases here:
- Expanding the supported range of OpenAPI schemas that are generated by default.
- Improving the ability for developers to customize the output.
We'll aim to bring the first type of change quickly in point releases. For the second kind we'd like to adopt a slower approach, to make sure we keep the API simple, and as widely applicable as possible, before we bring in API changes.
It's also possible that we'll end up implementing API documentation and API client
tooling that are driven by the OpenAPI schema. The apistar project has a
significant amount of work towards this. However, if we do so, we'll plan
on keeping any tooling outside of the core framework.
Funding
REST framework is a collaboratively funded project. If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan.
Every single sign-up helps us make REST framework long-term financially sustainable.
Many thanks to all our wonderful sponsors, and in particular to our premium backers, Sentry, Stream, ESG, Rollbar, Cadre, Kloudless, and Lights On Software.