django-rest-framework/docs/community/3.10-announcement.md

Django REST framework 3.10

Python 3 Only.

The 3.10 release is our first to drop support for Python 2.

Our supported Python versions are currently 3.5, 3.6, and 3.7.

Our support Django versions are currently 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.

---

Switching mode between CoreAPI and OpenAPI

Both the generateschema management command and get_schema_view() helper function will automatically switch between CoreAPI and OpenAPI modes, depending on the value of api_settings.DEFAULT_SCHEMA_CLASS.

If api_settings.DEFAULT_SCHEMA_CLASS is a subclass of rest_framework.schemas.coreapi.AutoSchema then CoreAPI mode will be selected. Otherwise the new OpenAPI will apply.

This means that, unless you previously overrode api_settings.DEFAULT_SCHEMA_CLASS, you automatically be opted-in to the new OpenAPI based schemas.

You can continue to use CoreAPI schemas by setting the appropriate default schema class:

# In settings.py
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

---

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 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.