3.12 release notes

docs/community/3.12-announcement.md

@@ -19,21 +19,63 @@
 
 # Django REST framework 3.12
 
-## Schema generation improvements
+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.
+## Grouping operations with tags.
 
-https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags
+Open API schemas will now automatically include tags, based on the first element
+in the URL path.
 
-#### Customizing the operation ID.
+For example...
 
-https://www.django-rest-framework.org/api-guide/schemas/#operationid
+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']`
 
-#### Support OpenAPI components.
+The tags used for a particular view may also be overridden...
 
-https://www.django-rest-framework.org/api-guide/schemas/#components
+```python
+class MyOrders(APIView):
+    schema = AutoSchema(tags=['users', 'orders'])
+    ...
+```
 
-#### More Public API
+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`
@@ -48,7 +90,8 @@ https://www.django-rest-framework.org/api-guide/schemas/#components
 * `map_field_validators`
 * `allows_filters`.
 
-See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema).
+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.
 
@@ -62,13 +105,41 @@ classes will correctly map the model field.
 
 There are a couple of significant improvements to the `SearchFilter` class.
 
-#### Support for nested search within `JSONField` and `HStoreField`
+### Nested searches against JSONField and HStoreField
 
-**TODO** Example to give better context.
+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.
 
-#### Support for searching against fields created using `annotate`
+```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']
+```
 
-**TODO** Example to give better context.
+### 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']
+```
 
 ---