mirror of
https://github.com/encode/django-rest-framework.git
synced 2025-04-26 20:13:42 +03:00
7915485c0d
* Update schema docs for OpenAPI * Begin v3.10 Release Announcement. * Update docs/topics/documenting-your-api.md Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com> * Update docs/topics/documenting-your-api.md Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com> * Update docs/topics/documenting-your-api.md Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com> * Update docs/topics/documenting-your-api.md Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com>
105 lines
3.5 KiB
Markdown
105 lines
3.5 KiB
Markdown
|
|
# 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
|