From e60dd2ba430cf53b9b935c7c5473341efdc77098 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 15 Jul 2019 11:50:06 +0100 Subject: [PATCH] Update 3.10 release docs --- docs/community/3.10-announcement.md | 95 +++++++++++++++++++---------- 1 file changed, 62 insertions(+), 33 deletions(-) diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md index 7197eb591..469e3d3f7 100644 --- a/docs/community/3.10-announcement.md +++ b/docs/community/3.10-announcement.md @@ -1,18 +1,45 @@ # Django REST framework 3.10 +## Python 3 Only. -* Reworked OpenAPI schema generation. -* 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 modelling Web APIs. +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 deprecates the old CoreAPI based schema generation, and introduces improved OpenAPI schema generation in its place. +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`** @@ -40,9 +67,13 @@ REST_FRAMEWORK = { ---- -### Quickstart +## Quickstart -To get going with `OpenAPI` schemas, use the `get_schema_view()` shortcut. +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`: @@ -62,43 +93,41 @@ urlpatterns = [ ] ``` -See the Schemas documentation for more details. +### Customization -### Feature Roadmap +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 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. +For specific per-view customizations, you can subclass `AutoSchema`, +making sure to set `schema = ` on the view. -So, for a fresh start with `OpenAPI`, customizing schema generation has two -simple rules: +For more details, see the [API Schema documentation](../api-guide/schemas.md). -* Subclass `SchemaGenerator` for schema-level cusomizations. -* Subclass `AutoSchema` for view-level customizations. +### API Documentation -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 some great third party options for documenting your API, based on the +OpenAPI schema. -There are two kinds of changes that easily predictable: +See the [Documenting you API](../topics/documenting-your-api.md) section for more details. -* General improvements which fill in gaps in the automatic schema generation. -* More use-case specific adjustments, which adjust the API of `SchemaGenerator` - or `AutoSchema` +--- + +## 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. -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]. +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