From 2deb6b42f156455562319b23a88ae1d047b83549 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 16 Oct 2018 13:58:25 +0100 Subject: [PATCH] Adding release notes --- docs/community/3.9-announcement.md | 85 ++++++++++++++++++++++++++---- mkdocs.yml | 1 + 2 files changed, 77 insertions(+), 9 deletions(-) diff --git a/docs/community/3.9-announcement.md b/docs/community/3.9-announcement.md index e1c641780..ee690f689 100644 --- a/docs/community/3.9-announcement.md +++ b/docs/community/3.9-announcement.md @@ -29,12 +29,71 @@ If you use REST framework commercially and would like to see this work continue, **[signing up for a paid plan][funding]**. -TODO: UPDATE SPONSORS. + +
-*We'd like to say thanks in particular our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://hello.machinalis.co.uk/), and [Rollbar](https://rollbar.com).* +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Auklet](https://auklet.io/), [Rollbar](https://rollbar.com), [Cadre](https://cadre.com), [Load Impact](https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf), and [Kloudless](https://hubs.ly/H0f30Lf0).* --- +## In-built OpenAPI schema support + +REST framework now has a first-pass at directly including OpenAPI schema support. + +Specifically: + +* There are now `OpenAPIRenderer`, and `JSONOpenAPIRenderer` classes that deal with encoding `coreapi.Document` instances into OpenAPI YAML or OpenAPI JSON. +* The `get_schema_view(...)` method now defaults to OpenAPI YAML, with CoreJSON as a secondary +option if it is selected via HTTP content negotiation. +* There is a new management command `generateschema`, which you can use to dump +the schema into your repository. + +Here's an example of adding an OpenAPI schema to the URL conf: + +```python +from rest_framework.schemas import get_schema_view +from rest_framework.renderers import JSONOpenAPIRenderer + +schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + renderer_classes=[JSONOpenAPIRenderer] +) + +urlpatterns = [ + url('^schema.json$', schema_view), + ... +] +``` + +And here's how you can use the `generateschema` management command: + +``` +$ python manage.py generateschema --format openapi > schema.yml +``` + +## Composable permission classes + +You can now compose permission classes using the and/or operators, `&` and `|`. + +For example... + +```python +permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)] +``` + +If you're using custom permission classes then make sure that you are subclassing +from `BasePermission` in order to enable this support. + ## ViewSet _Extra Actions_ available in the Browsable API Following the introduction of the `action` decorator in v3.8, _extra actions_ defined on a ViewSet are now available @@ -44,10 +103,6 @@ from the Browsable API. When defined, a dropdown of "Extra Actions", appropriately filtered to detail/non-detail actions, is displayed. -## In-built OpenAPI schema support - -TODO - --- ## Deprecations @@ -92,17 +147,29 @@ For function based views the `@schema` decorator can be used to exclude the view ## Minor fixes and improvements -There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page -for a complete listing. +There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page for a complete listing. ## What's next +We're planning to iteratively working towards OpenAPI becoming the standard schema +representation. This will mean that the `coreapi` dependency will gradually become +removed, and we'll instead generate the schema directly, rather than building +a CoreAPI `Document` object. -TODO... +OpenAPI has clearly become the standard for specifying Web APIs, so there's not +much value any more in our schema-agnostic document model. Making this change +will mean that we'll more easily be able to take advantage of the full set of +OpenAPI functionality. +This will also make a wider range of tooling available. + +We'll focus on continuing to develop the `apistar` library and client tool into +a recommended option for generating API docs, validating API schemas, and +providing a dynamic client library. [funding]: funding.md [gh5886]: https://github.com/encode/django-rest-framework/issues/5886 [gh5705]: https://github.com/encode/django-rest-framework/issues/5705 [openapi]: https://www.openapis.org/ +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors diff --git a/mkdocs.yml b/mkdocs.yml index fbdb8d779..83b3c8141 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,6 +65,7 @@ pages: - 'Contributing to REST framework': 'community/contributing.md' - 'Project management': 'community/project-management.md' - 'Release Notes': 'community/release-notes.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' - '3.6 Announcement': 'community/3.6-announcement.md'