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

Django REST framework 3.10

• Reworked OpenAPI schema generation.
• Python 3 only.

OpenAPI Schema Generation.

Since we first introduced schema support in Django REST Framework 3.5, OpenAPI has emerged as the widely adopted standard for modelling Web APIs.

This release deprecates the old CoreAPI based schema generation, and introduces improved OpenAPI schema generation in its place.

---

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

To get going with OpenAPI schemas, 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'),
    # ...
]

See the Schemas documentation for more details.

Feature Roadmap

For v3.7 (with CoreAPI) we tried to anticipate customizations that people were likely to need. (Introducing manual_fields and ManaualSchema, for example.) These were under-utilised. They weren't the right abstractions.

So, for a fresh start with OpenAPI, customizing schema generation has two simple rules:

• Subclass SchemaGenerator for schema-level cusomizations.
• Subclass AutoSchema for view-level customizations.

We'll wait to see what subclasses people actually come up with, for the customizations they actually need, before trying to bring that back into the core framework.

There are two kinds of changes that easily predictable:

• General improvements which fill in gaps in the automatic schema generation.
• More use-case specific adjustments, which adjust the API of SchemaGenerator or AutoSchema

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.

We trust that approach makes sense.

Deprecating CoreAPI Schema Generation.

The in-built docs that were introduced in Django REST Framework v3.5 were built on CoreAPI. These are now deprecated. You may continue to use them but they will be removed in Django REST Framework v 3.12.

You should migrate to using the new OpenAPI based schema generation as soon as you can.

We have removed the old documentation for the CoreAPI based schema generation. You may view the Legacy CoreAPI documentation here.