diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md new file mode 100644 index 000000000..7197eb591 --- /dev/null +++ b/docs/community/3.10-announcement.md @@ -0,0 +1,104 @@ + +# 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 diff --git a/mkdocs.yml b/mkdocs.yml index 87e51cdb3..61cf25e77 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,6 +64,7 @@ pages: - 'Contributing to REST framework': 'community/contributing.md' - 'Project management': 'community/project-management.md' - 'Release Notes': 'community/release-notes.md' + - '3.10 Announcement': 'community/3.10-announcement.md' - '3.9 Announcement': 'community/3.9-announcement.md' - '3.8 Announcement': 'community/3.8-announcement.md' - '3.7 Announcement': 'community/3.7-announcement.md'