diff --git a/docs/community/3.12-announcement.md b/docs/community/3.12-announcement.md new file mode 100644 index 0000000000..9d2220933c --- /dev/null +++ b/docs/community/3.12-announcement.md @@ -0,0 +1,169 @@ + + +# Django REST framework 3.12 + +REST framework 3.12 brings a handful of refinements to the OpenAPI schema +generation, plus support for Django's new database-agnostic `JSONField`, +and some improvements to the `SearchFilter` class. + +## Grouping operations with tags. + +Open API schemas will now automatically include tags, based on the first element +in the URL path. + +For example... + +Method | Path | Tags +--------------------------------|-----------------|------------- +`GET`, `PUT`, `PATCH`, `DELETE` | `/users/{id}/` | `['users']` +`GET`, `POST` | `/users/` | `['users']` +`GET`, `PUT`, `PATCH`, `DELETE` | `/orders/{id}/` | `['orders']` +`GET`, `POST` | `/orders/` | `['orders']` + +The tags used for a particular view may also be overridden... + +```python +class MyOrders(APIView): + schema = AutoSchema(tags=['users', 'orders']) + ... +``` + +See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags) for more information. + +## Customizing the operation ID. + +REST framework automatically determines operation IDs to use in OpenAPI +schemas. The latest version provides more control for overriding the behaviour +used to generate the operation IDs. + +See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#operationid) for more information. + +## Support for OpenAPI components. + +In order to output more graceful OpenAPI schemes, REST framework 3.12 now +defines components in the schema, and then references them inside request +and response objects. This is in contrast with the previous approach, which +fully expanded the request and response bodies for each operation. + +The names used for a component default to using the serializer class name, [but +may be overridden if needed](https://www.django-rest-framework.org/api-guide/schemas/#components +)... + +```python +class MyOrders(APIView): + schema = AutoSchema(component_name="OrderDetails") +``` + +## More Public API + +Many methods on the `AutoSchema` class have now been promoted to public API, +allowing you to more fully customize the schema generation. The following methods +are now available for overriding... + +* `get_path_parameters` +* `get_pagination_parameters` +* `get_filter_parameters` +* `get_request_body` +* `get_responses` +* `get_serializer` +* `get_paginator` +* `map_serializer` +* `map_field` +* `map_choice_field` +* `map_field_validators` +* `allows_filters`. + +See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#per-view-customization) +for details on using custom `AutoSchema` subclasses. + +## Support for JSONField. + +Django 3.1 deprecated the existing `django.contrib.postgres.fields.JSONField` +in favour of a new database-agnositic `JSONField`. + +REST framework 3.12 now supports this new model field, and `ModelSerializer` +classes will correctly map the model field. + +## SearchFilter improvements + +There are a couple of significant improvements to the `SearchFilter` class. + +### Nested searches against JSONField and HStoreField + +The class now supports nested search within `JSONField` and `HStoreField`, using +the double underscore notation for traversing which element of the field the +search should apply to. + +```python +class SitesSearchView(generics.ListAPIView): + """ + An API view to return a list of archaeological sites, optionally filtered + by a search against the site name or location. (Location searches are + matched against the region and country names.) + """ + queryset = Sites.objects.all() + serializer_class = SitesSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['site_name', 'location__region', 'location__country'] +``` + +### Searches against annotate fields + +Django allows querysets to create additional virtual fields, using the `.annotate` +method. We now support searching against annotate fields. + +```python +class PublisherSearchView(generics.ListAPIView): + """ + Search for publishers, optionally filtering the search against the average + rating of all their books. + """ + queryset = Publisher.objects.annotate(avg_rating=Avg('book__rating')) + serializer_class = PublisherSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['avg_rating'] +``` + +--- + +## Funding + +REST framework is a *collaboratively funded project*. If you use +REST framework commercially we strongly encourage you to invest in its +continued development by **[signing up for a paid plan][funding]**. + +*Every single sign-up helps us make REST framework long-term financially sustainable.* + + +
+ +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), [Lights On Software](https://lightsonsoftware.com), and [Retool](https://retool.com/?utm_source=djangorest&utm_medium=sponsorship).* + +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: funding.md diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 0e634aa1e9..1d1b4353f1 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -36,11 +36,58 @@ You can determine your currently installed version using `pip show`: ## 3.11.x series +### 3.12.0 + +* Add `--file` option to `generateschema` command. [#7130] +* Support `tags` for OpenAPI schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags). [#7184] +* Support customising the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] +* Support OpenAPI components for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#components). [#7124] +* The following methods on `AutoSchema` become public API: `get_path_parameters`, `get_pagination_parameters`, `get_filter_parameters`, `get_request_body`, `get_responses`, `get_serializer`, `get_paginator`, `map_serializer`, `map_field`, `map_choice_field`, `map_field_validators`, `allows_filters`. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema) +* Add support for Django 3.1's database-agnositic `JSONField`. [#7467] +* `SearchFilter` now supports nested search on `JSONField` and `HStoreField` model fields. [#7121] +* `SearchFilter` now supports searching on `annotate()` fields. [#6240] +* The authtoken model no longer exposes the `pk` in the admin URL. [#7341] +* Add `__repr__` for Request instances. [#7239] +* UTF-8 decoding with Latin-1 fallback for basic auth credentials. [#7193] +* CharField treats surrogate characters as a validation failure. [#7026] +* Don't include callables as default values in schemas. [#7105] +* Improve `ListField` schema output to include all available child information. [#7137] +* Allow `default=False` to be included for `BooleanField` schema outputs. [#7165] +* Include `"type"` information in `ChoiceField` schema outputs. [#7161] +* Include `"type": "object"` on schema objects. [#7169] +* Don't include component in schema output for DELETE requests. [#7229] +* Fix schema types for `DecimalField`. [#7254] +* Fix schema generation for `ObtainAuthToken` view. [#7211] +* Support passing `context=...` to view `.get_serializer()` methods. [#7298] +* Pass custom code to `PermissionDenied` if permission class has one set. [#7306] +* Include "example" in schema pagination output. [#7275] +* Default status code of 201 on schema output for POST requests. [#7206] +* Use camelCase for operation IDs in schema output. [#7208] +* Warn if duplicate operation IDs exist in schema output. [#7207] +* Improve handling of decimal type when mapping `ChoiceField` to a schema output. [#7264] +* Disable YAML aliases for OpenAPI schema outputs. [#7131] +* Fix action URL names for APIs included under a namespaced URL. [#7287] +* Update jQuery version from 3.4 to 3.5. [#7313] +* Fix `UniqueTogether` handling when serializer fields use `source=...`. [#7143] +* HTTP `HEAD` requests now set `self.action` correctly on a ViewSet instance. [#7223] +* Return a valid OpenAPI schema for the case where no API schema paths exist. [#7125] +* Include tests in package distribution. [#7145] +* Allow type checkers to support annotations like `ModelSerializer[Author]`. [#7385] +* Don't include invalid `charset=None` portion in the request `Content-Type` header when using APIClient. [#7400] +* Fix `\Z`/`\z` tokens in OpenAPI regexs. [#7389] +* Fix `PrimaryKeyRelatedField` and `HyperlinkedRelatedField` when source field is actually a property. [#7142] +* `Token.generate_key` is now a class method. [#7502] +* `@action` warns if method is wrapped in a decorator that does not preserve information using `@functools.wraps`. [#7098] + +--- + +## 3.11.x series + ### 3.11.0 **Date**: 12th December 2019 -* Drop `.set_context` API [in favour of a `requires_context` marker](../3.11-announcement#validator-default-context). +* Drop `.set_context` API [in favour of a `requires_context` marker](3.11-announcement.md#validator-default-context). * Changed default widget for TextField with choices to select box. [#6892][gh6892] * Supported nested writes on non-relational fields, such as JSONField. [#6916][gh6916] * Include request/response media types in OpenAPI schemas, based on configured parsers/renderers. [#6865][gh6865] diff --git a/mkdocs.yml b/mkdocs.yml index 484971a715..573898bca0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ nav: - 'Contributing to REST framework': 'community/contributing.md' - 'Project management': 'community/project-management.md' - 'Release Notes': 'community/release-notes.md' + - '3.12 Announcement': 'community/3.12-announcement.md' - '3.11 Announcement': 'community/3.11-announcement.md' - '3.10 Announcement': 'community/3.10-announcement.md' - '3.9 Announcement': 'community/3.9-announcement.md' diff --git a/rest_framework/__init__.py b/rest_framework/__init__.py index 8f2bc4466f..afb2d34292 100644 --- a/rest_framework/__init__.py +++ b/rest_framework/__init__.py @@ -8,7 +8,7 @@ """ __title__ = 'Django REST framework' -__version__ = '3.11.0' +__version__ = '3.12.0' __author__ = 'Tom Christie' __license__ = 'BSD 3-Clause' __copyright__ = 'Copyright 2011-2019 Encode OSS Ltd'