* Reworked OpenAPI schema generation.

* Python 3 only.

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:

REST_FRAMEWORK = {

'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',

}

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.

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.

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][legacy-core-api-docs].

[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/master/docs/coreapi/index.md

- '3.10 Announcement': 'community/3.10-announcement.md'