mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-25 02:53:58 +03:00
Placeholder for 3.12 release (#7379)
* Placeholder for 3.12 release * Updating release notes * Updating release notes * Updating release notes * Update release notes * Fix typo * Basic structure for release announcement * 3.12 release notes * Version 3.12.0
This commit is contained in:
Tom Christie
GitHub
parent
9ee67bbff7
commit
6f7aad8ffa
169
docs/community/3.12-announcement.md
Normal file
169
docs/community/3.12-announcement.md
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
<style>
|
||||
.promo li a {
|
||||
float: left;
|
||||
width: 130px;
|
||||
height: 20px;
|
||||
text-align: center;
|
||||
margin: 10px 30px;
|
||||
padding: 150px 0 0 0;
|
||||
background-position: 0 50%;
|
||||
background-size: 130px auto;
|
||||
background-repeat: no-repeat;
|
||||
font-size: 120%;
|
||||
color: black;
|
||||
}
|
||||
.promo li {
|
||||
list-style: none;
|
||||
}
|
||||
</style>
|
||||
|
||||
# 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.*
|
||||
|
||||
<ul class="premium-promo promo">
|
||||
<li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
|
||||
<li><a href="https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
|
||||
<li><a href="https://software.esg-usa.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/esg-new-logo.png)">ESG</a></li>
|
||||
<li><a href="https://rollbar.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rollbar2.png)">Rollbar</a></li>
|
||||
<li><a href="https://cadre.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/cadre.png)">Cadre</a></li>
|
||||
<li><a href="https://hubs.ly/H0f30Lf0" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/kloudless-plus-text.png)">Kloudless</a></li>
|
||||
<li><a href="https://lightsonsoftware.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/lightson-dark.png)">Lights On Software</a></li>
|
||||
<li><a href="https://retool.com/?utm_source=djangorest&utm_medium=sponsorship" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/retool-sidebar.png)">Retool</a></li>
|
||||
</ul>
|
||||
<div style="clear: both; padding-bottom: 20px;"></div>
|
||||
|
||||
*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
|
||||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user