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

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

---

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

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

```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'),
    # ...
]
```

### 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-guide/schemas.md).

### API Documentation

There are some great third party options for documenting your API, based on the
OpenAPI schema.

See the [Documenting you API](../topics/documenting-your-api.md) 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.

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