# 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:

```python
# 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`:

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

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