encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2025-07-27 08:29:59 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: lint

Browse Source
This commit is contained in:
Shyamkumar Yadav 2022-10-08 17:46:17 +05:30
parent 79604a895e
commit 7ff1facd53
20 changed files with 261 additions and 263 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/community/3.0-announcement.md
View File

@ -58,7 +58,6 @@ Instead of passing the files argument separately:
# Don't do this... # Don't do this...
ExampleSerializer(data=request.DATA, files=request.FILES) ExampleSerializer(data=request.DATA, files=request.FILES)
The usage of `request.QUERY_PARAMS` is now pending deprecation in favor of the lowercased `request.query_params`. The usage of `request.QUERY_PARAMS` is now pending deprecation in favor of the lowercased `request.query_params`.
--- ---
@ -791,7 +790,7 @@ Both styles "`PUT` as 404" and "`PUT` as create" can be valid in different circu
If you need to restore the previous behavior you may want to include [this `AllowPUTAsCreateMixin` class](https://gist.github.com/tomchristie/a2ace4577eff2c603b1b) as a mixin to your views. If you need to restore the previous behavior you may want to include [this `AllowPUTAsCreateMixin` class](https://gist.github.com/tomchristie/a2ace4577eff2c603b1b) as a mixin to your views.
#### Customizing error responses. #### Customizing error responses.
The generic views now raise `ValidationFailed` exception for invalid data. This exception is then dealt with by the exception handler, rather than the view returning a `400 Bad Request` response directly. The generic views now raise `ValidationFailed` exception for invalid data. This exception is then dealt with by the exception handler, rather than the view returning a `400 Bad Request` response directly.
@ -807,7 +806,7 @@ This makes it far easier to use a different style for `OPTIONS` responses throug
--- ---
## Serializers as HTML forms ## Serializers as HTML forms
REST framework 3.0 includes templated HTML form rendering for serializers. REST framework 3.0 includes templated HTML form rendering for serializers.

4
docs/community/3.1-announcement.md
View File

@ -129,7 +129,7 @@ Many thanks to [Craig Blaszczyk](https://github.com/jakul) for helping push this
--- ---
## New field types ## New field types
Django 1.8's new `ArrayField`, `HStoreField` and `UUIDField` are now all fully supported. Django 1.8's new `ArrayField`, `HStoreField` and `UUIDField` are now all fully supported.
@ -192,7 +192,7 @@ All these attributes and options will still work in 3.1, but their usage will ra
--- ---
## What's next? ## What's next?
The next focus will be on HTML renderings of API output and will include: The next focus will be on HTML renderings of API output and will include:

6
docs/community/3.10-announcement.md
View File

@ -39,12 +39,10 @@ update your REST framework settings to include `DEFAULT_SCHEMA_CLASS` explicitly
**settings.py**: **settings.py**:
```python
REST_FRAMEWORK = { REST_FRAMEWORK = {
... ...
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
} }
```
You'll still be able to keep using CoreAPI schemas, API docs, and client for the 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 foreseeable future. We'll aim to ensure that the CoreAPI schema generator remains
@ -54,7 +52,7 @@ from REST framework, scheduled for version 3.12.
We have removed the old documentation for the CoreAPI based schema generation. We have removed the old documentation for the CoreAPI based schema generation.
You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs]. You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs].
---- ---
## OpenAPI Quickstart ## OpenAPI Quickstart
@ -66,7 +64,6 @@ shortcut.
In your `urls.py`: In your `urls.py`:
```python
from rest_framework.schemas import get_schema_view from rest_framework.schemas import get_schema_view
urlpatterns = [ urlpatterns = [
@ -80,7 +77,6 @@ urlpatterns = [
), name='openapi-schema'), ), name='openapi-schema'),
# ... # ...
] ]
```
### Customization ### Customization

6
docs/community/3.11-announcement.md
View File

@ -41,7 +41,6 @@ include:
In this example view operation descriptions for the `get` and `post` methods will In this example view operation descriptions for the `get` and `post` methods will
be extracted from the class docstring: be extracted from the class docstring:
```python
class DocStringExampleListView(APIView): class DocStringExampleListView(APIView):
""" """
get: A description of my GET operation. get: A description of my GET operation.
@ -54,7 +53,6 @@ post: A description of my POST operation.
def post(self, request, *args, **kwargs): def post(self, request, *args, **kwargs):
... ...
```
## Validator / Default Context ## Validator / Default Context
@ -71,23 +69,19 @@ The `__call__` method should then include an additional `serializer_field` argum
Validator implementations will look like this: Validator implementations will look like this:
```python
class CustomValidator: class CustomValidator:
requires_context = True requires_context = True
def __call__(self, value, serializer_field): def __call__(self, value, serializer_field):
... ...
```
Default implementations will look like this: Default implementations will look like this:
```python
class CustomDefault: class CustomDefault:
requires_context = True requires_context = True
def __call__(self, serializer_field): def __call__(self, serializer_field):
... ...
```
--- ---

41
docs/community/3.12-announcement.md
View File

@ -30,20 +30,39 @@ in the URL path.
For example... For example...
Method | Path | Tags <table border=1>
--------------------------------|-----------------|------------- <tr>
`GET`, `PUT`, `PATCH`, `DELETE` | `/users/{id}/` | `['users']` <th>Method</th>
`GET`, `POST` | `/users/` | `['users']` <th>Path</th>
`GET`, `PUT`, `PATCH`, `DELETE` | `/orders/{id}/` | `['orders']` <th>Tags</th>
`GET`, `POST` | `/orders/` | `['orders']` </tr>
<tr>
<td><code>GET</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code></td>
<td><code>/users/{id}/</code></td>
<td><code>['users']</code></td>
</tr>
<tr>
<td><code>GET</code>, <code>POST</code></td>
<td><code>/users/</code></td>
<td><code>['users']</code></td>
</tr>
<tr>
<td><code>GET</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code></td>
<td><code>/orders/{id}/</code></td>
<td><code>['orders']</code></td>
</tr>
<tr>
<td><code>GET</code>, <code>POST</code></td>
<td><code>/orders/</code></td>
<td><code>['orders']</code></td>
</tr>
</table>
The tags used for a particular view may also be overridden... The tags used for a particular view may also be overridden...
```python
class MyOrders(APIView): class MyOrders(APIView):
schema = AutoSchema(tags=['users', 'orders']) 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. See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags) for more information.
@ -66,10 +85,8 @@ 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 may be overridden if needed](https://www.django-rest-framework.org/api-guide/schemas/#components
)... )...
```python
class MyOrders(APIView): class MyOrders(APIView):
schema = AutoSchema(component_name="OrderDetails") schema = AutoSchema(component_name="OrderDetails")
```
## More Public API ## More Public API
@ -111,7 +128,6 @@ The class now supports nested search within `JSONField` and `HStoreField`, using
the double underscore notation for traversing which element of the field the the double underscore notation for traversing which element of the field the
search should apply to. search should apply to.
```python
class SitesSearchView(generics.ListAPIView): class SitesSearchView(generics.ListAPIView):
""" """
An API view to return a list of archaeological sites, optionally filtered An API view to return a list of archaeological sites, optionally filtered
@ -122,14 +138,12 @@ class SitesSearchView(generics.ListAPIView):
serializer_class = SitesSerializer serializer_class = SitesSerializer
filter_backends = [filters.SearchFilter] filter_backends = [filters.SearchFilter]
search_fields = ['site_name', 'location__region', 'location__country'] search_fields = ['site_name', 'location__region', 'location__country']
```
### Searches against annotate fields ### Searches against annotate fields
Django allows querysets to create additional virtual fields, using the `.annotate` Django allows querysets to create additional virtual fields, using the `.annotate`
method. We now support searching against annotate fields. method. We now support searching against annotate fields.
```python
class PublisherSearchView(generics.ListAPIView): class PublisherSearchView(generics.ListAPIView):
""" """
Search for publishers, optionally filtering the search against the average Search for publishers, optionally filtering the search against the average
@ -139,7 +153,6 @@ class PublisherSearchView(generics.ListAPIView):
serializer_class = PublisherSerializer serializer_class = PublisherSerializer
filter_backends = [filters.SearchFilter] filter_backends = [filters.SearchFilter]
search_fields = ['avg_rating'] search_fields = ['avg_rating']
```
--- ---

4
docs/community/3.13-announcement.md
View File

@ -40,15 +40,11 @@ From REST framework 3.13 onwards, this is now *explicitly enforced*.
The most feasible cases where users might be accidentally omitting the keyword arguments The most feasible cases where users might be accidentally omitting the keyword arguments
are likely in the composite fields, `ListField` and `DictField`. For instance... are likely in the composite fields, `ListField` and `DictField`. For instance...
```python
aliases = serializers.ListField(serializers.CharField()) aliases = serializers.ListField(serializers.CharField())
```
They must now use the more explicit keyword argument style... They must now use the more explicit keyword argument style...
```python
aliases = serializers.ListField(child=serializers.CharField()) aliases = serializers.ListField(child=serializers.CharField())
```
This change has been made because using positional arguments here *does not* result in the expected behaviour. This change has been made because using positional arguments here *does not* result in the expected behaviour.

1
docs/community/3.14-announcement.md
View File

@ -44,7 +44,6 @@ skipped depending on the other arguments.
See Pull Request [#7574](https://github.com/encode/django-rest-framework/pull/7574) for more details. See Pull Request [#7574](https://github.com/encode/django-rest-framework/pull/7574) for more details.
## Make Open API `get_reference` public. ## Make Open API `get_reference` public.
Returns a reference to the serializer component. This may be useful if you override `get_schema()`. Returns a reference to the serializer component. This may be useful if you override `get_schema()`.

2
docs/community/3.5-announcement.md
View File

@ -59,7 +59,6 @@ For example, to include a swagger schema to your API, you would do the following
* Include the schema view in your URL conf: * Include the schema view in your URL conf:
```py
from rest_framework.schemas import get_schema_view from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
@ -72,7 +71,6 @@ urlpatterns = [
path('swagger/', schema_view), path('swagger/', schema_view),
... ...
] ]
```
There have been a large number of fixes to the schema generation. These should There have been a large number of fixes to the schema generation. These should
resolve issues for anyone using the latest version of the `django-rest-swagger` resolve issues for anyone using the latest version of the `django-rest-swagger`

3
docs/community/3.8-announcement.md
View File

@ -29,7 +29,6 @@ the foundations for future changes.
If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by
**[signing up for a paid&nbsp;plan][funding]**. **[signing up for a paid&nbsp;plan][funding]**.
*We'd like to say thanks in particular our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://machinalis.com/), and [Rollbar](https://rollbar.com).* *We'd like to say thanks in particular our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://machinalis.com/), and [Rollbar](https://rollbar.com).*
--- ---
@ -68,7 +67,6 @@ The new `action` decorator takes a boolean `detail` argument.
* Replace `detail_route` uses with `@action(detail=True)`. * Replace `detail_route` uses with `@action(detail=True)`.
* Replace `list_route` uses with `@action(detail=False)`. * Replace `list_route` uses with `@action(detail=False)`.
### `exclude_from_schema` ### `exclude_from_schema`
Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` decorator are now deprecated. They will be removed entirely in 3.9. Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` decorator are now deprecated. They will be removed entirely in 3.9.
@ -84,7 +82,6 @@ For function based views the `@schema` decorator can be used to exclude the view
There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page 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. for a complete listing.
## What's next ## What's next
We're currently working towards moving to using [OpenAPI][openapi] as our default schema output. We'll also be revisiting our API documentation generation and client libraries. We're currently working towards moving to using [OpenAPI][openapi] as our default schema output. We'll also be revisiting our API documentation generation and client libraries.

21
docs/community/3.9-announcement.md
View File

@ -19,7 +19,7 @@
# Django REST framework 3.9 # Django REST framework 3.9
The 3.9 release gives access to _extra actions_ in the Browsable API, introduces composable permissions and built-in [OpenAPI][openapi] schema support. (Formerly known as Swagger) The 3.9 release gives access to *extra actions* in the Browsable API, introduces composable permissions and built-in [OpenAPI][openapi] schema support. (Formerly known as Swagger)
--- ---
@ -28,7 +28,6 @@ The 3.9 release gives access to _extra actions_ in the Browsable API, introduces
If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by
**[signing up for a paid&nbsp;plan][funding]**. **[signing up for a paid&nbsp;plan][funding]**.
<ul class="premium-promo promo"> <ul class="premium-promo promo">
<li><a href="https://www.rover.com/careers/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rover_130x130.png)">Rover.com</a></li> <li><a href="https://www.rover.com/careers/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rover_130x130.png)">Rover.com</a></li>
<li><a href="https://sentry.io/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li> <li><a href="https://sentry.io/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
@ -59,7 +58,6 @@ the schema into your repository.
Here's an example of adding an OpenAPI schema to the URL conf: 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.schemas import get_schema_view
from rest_framework.renderers import JSONOpenAPIRenderer from rest_framework.renderers import JSONOpenAPIRenderer
from django.urls import path from django.urls import path
@ -74,13 +72,10 @@ urlpatterns = [
path('schema.json', schema_view), path('schema.json', schema_view),
... ...
] ]
```
And here's how you can use the `generateschema` management command: And here's how you can use the `generateschema` management command:
```shell
$ python manage.py generateschema --format openapi > schema.yml $ python manage.py generateschema --format openapi > schema.yml
```
There's lots of different tooling that you can use for working with OpenAPI There's lots of different tooling that you can use for working with OpenAPI
schemas. One option that we're working on is the [API Star](https://docs.apistar.com/) schemas. One option that we're working on is the [API Star](https://docs.apistar.com/)
@ -88,17 +83,13 @@ command line tool.
You can use `apistar` to validate your API schema: You can use `apistar` to validate your API schema:
```shell
$ apistar validate --path schema.json --format openapi $ apistar validate --path schema.json --format openapi
✓ Valid OpenAPI schema. ✓ Valid OpenAPI schema.
```
Or to build API documentation: Or to build API documentation:
```shell
$ apistar docs --path schema.json --format openapi $ apistar docs --path schema.json --format openapi
✓ Documentation built at "build/index.html". ✓ Documentation built at "build/index.html".
```
API Star also includes a [dynamic client library](https://docs.apistar.com/client-library/) API Star also includes a [dynamic client library](https://docs.apistar.com/client-library/)
that uses an API schema to automatically provide a client library interface for making requests. that uses an API schema to automatically provide a client library interface for making requests.
@ -109,16 +100,14 @@ You can now compose permission classes using the and/or operators, `&` and `|`.
For example... For example...
```python
permission_classes = [IsAuthenticated & (ReadOnly | IsAdminUser)] permission_classes = [IsAuthenticated & (ReadOnly | IsAdminUser)]
```
If you're using custom permission classes then make sure that you are subclassing If you're using custom permission classes then make sure that you are subclassing
from `BasePermission` in order to enable this support. from `BasePermission` in order to enable this support.
## ViewSet _Extra Actions_ available in the Browsable API ## 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 Following the introduction of the `action` decorator in v3.8, *extra actions* defined on a ViewSet are now available
from the Browsable API. from the Browsable API.
![Extra Actions displayed in the Browsable API](https://user-images.githubusercontent.com/2370209/32976956-1ca9ab7e-cbf1-11e7-981a-a20cb1e83d63.png) ![Extra Actions displayed in the Browsable API](https://user-images.githubusercontent.com/2370209/32976956-1ca9ab7e-cbf1-11e7-981a-a20cb1e83d63.png)
@ -177,7 +166,6 @@ For function-based views the `@schema` decorator can be used to exclude the view
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 ## What's next
We're planning to iteratively work towards OpenAPI becoming the standard schema We're planning to iteratively work towards OpenAPI becoming the standard schema
@ -205,9 +193,6 @@ web server, as well as lots of functionality planned for the [Starlette](https:/
web framework, which is building a foundational set of tooling for working with web framework, which is building a foundational set of tooling for working with
ASGI. ASGI.
[funding]: funding.md [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/ [openapi]: https://www.openapis.org/
[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors

2
docs/coreapi/7-schemas-and-client-libraries.md
View File

@ -48,7 +48,6 @@ YAML-based OpenAPI format.
We can now include a schema for our API, by including an autogenerated schema We can now include a schema for our API, by including an autogenerated schema
view in our URL configuration. view in our URL configuration.
```python
from rest_framework.schemas import get_schema_view from rest_framework.schemas import get_schema_view
schema_view = get_schema_view(title='Pastebin API') schema_view = get_schema_view(title='Pastebin API')
@ -57,7 +56,6 @@ urlpatterns = [
   path('schema/', schema_view),    path('schema/', schema_view),
... ...
] ]
```
If you visit the `/schema/` endpoint in a browser you should now see `corejson` If you visit the `/schema/` endpoint in a browser you should now see `corejson`
representation become available as an option. representation become available as an option.

10
docs/coreapi/from-documenting-your-api.md
View File

@ -1,7 +1,7 @@
## Built-in API documentation # Built-in API documentation
---- ---
**DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details. **DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details.
@ -10,7 +10,7 @@ If you are looking for information regarding schemas, you might want to look at
1. [Schema](../api-guide/schemas.md) 1. [Schema](../api-guide/schemas.md)
2. [Documenting your API](../topics/documenting-your-api.md) 2. [Documenting your API](../topics/documenting-your-api.md)
---- ---
The built-in API documentation includes: The built-in API documentation includes:
@ -55,10 +55,8 @@ You may ensure views are given a `request` instance by calling `include_docs_url
path('docs/', include_docs_urls(title='My API title', public=False)) path('docs/', include_docs_urls(title='My API title', public=False))
] ]
--- ---
### Documenting your views ### Documenting your views
You can document your views by including docstrings that describe each of the available actions. You can document your views by including docstrings that describe each of the available actions.
@ -116,7 +114,6 @@ as delimiters or by attaching the documentation to action mapping methods.
A description of the put method on the custom action. A description of the put method on the custom action.
""" """
### `documentation` API Reference ### `documentation` API Reference
The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`. The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`.
@ -158,7 +155,6 @@ The `rest_framework.documentation` module provides three helper functions to hel
* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. * `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
### Customising code samples ### Customising code samples
The built-in API documentation includes automatically generated code samples for The built-in API documentation includes automatically generated code samples for

3
docs/index.md
View File

@ -240,7 +240,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[pygments]: https://pypi.org/project/Pygments/ [pygments]: https://pypi.org/project/Pygments/
[django-filter]: https://pypi.org/project/django-filter/ [django-filter]: https://pypi.org/project/django-filter/
[django-guardian]: https://github.com/django-guardian/django-guardian [django-guardian]: https://github.com/django-guardian/django-guardian
[index]: .
[oauth1-section]: api-guide/authentication/#django-rest-framework-oauth [oauth1-section]: api-guide/authentication/#django-rest-framework-oauth
[oauth2-section]: api-guide/authentication/#django-oauth-toolkit [oauth2-section]: api-guide/authentication/#django-oauth-toolkit
[serializer-section]: api-guide/serializers#serializers [serializer-section]: api-guide/serializers#serializers
@ -263,5 +262,3 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
[stack-overflow]: https://stackoverflow.com/ [stack-overflow]: https://stackoverflow.com/
[django-rest-framework-tag]: https://stackoverflow.com/questions/tagged/django-rest-framework [django-rest-framework-tag]: https://stackoverflow.com/questions/tagged/django-rest-framework
[security-mail]: mailto:rest-framework-security@googlegroups.com
[twitter]: https://twitter.com/_tomchristie

1
docs/topics/browsable-api.md
View File

@ -4,7 +4,6 @@
> >
> &mdash; [Alfred North Whitehead][cite], An Introduction to Mathematics (1911) > &mdash; [Alfred North Whitehead][cite], An Introduction to Mathematics (1911)
API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`.
## URLs ## URLs

9
docs/topics/documenting-your-api.md
View File

@ -25,7 +25,6 @@ Assuming you've followed the example from the schemas documentation for routing
a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be
this: this:
```html
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
@ -54,12 +53,10 @@ this:
</script> </script>
</body> </body>
</html> </html>
```
Save this in your templates folder as `swagger-ui.html`. Then route a Save this in your templates folder as `swagger-ui.html`. Then route a
`TemplateView` in your project's URL conf: `TemplateView` in your project's URL conf:
```python
from django.views.generic import TemplateView from django.views.generic import TemplateView
urlpatterns = [ urlpatterns = [
@ -71,7 +68,6 @@ urlpatterns = [
extra_context={'schema_url':'openapi-schema'} extra_context={'schema_url':'openapi-schema'}
), name='swagger-ui'), ), name='swagger-ui'),
] ]
```
See the [Swagger UI documentation][swagger-ui] for advanced usage. See the [Swagger UI documentation][swagger-ui] for advanced usage.
@ -81,7 +77,6 @@ Assuming you've followed the example from the schemas documentation for routing
a dynamic `SchemaView`, a minimal Django template for using ReDoc might be a dynamic `SchemaView`, a minimal Django template for using ReDoc might be
this: this:
```html
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
@ -103,12 +98,10 @@ this:
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body> </body>
</html> </html>
```
Save this in your templates folder as `redoc.html`. Then route a `TemplateView` Save this in your templates folder as `redoc.html`. Then route a `TemplateView`
in your project's URL conf: in your project's URL conf:
```python
from django.views.generic import TemplateView from django.views.generic import TemplateView
urlpatterns = [ urlpatterns = [
@ -120,7 +113,6 @@ urlpatterns = [
extra_context={'schema_url':'openapi-schema'} extra_context={'schema_url':'openapi-schema'}
), name='redoc'), ), name='redoc'),
] ]
```
See the [ReDoc documentation][redoc] for advanced usage. See the [ReDoc documentation][redoc] for advanced usage.
@ -139,7 +131,6 @@ generation tools like `swagger-codegen`.
This also translates into a very useful interactive documentation viewer in the form of `swagger-ui`: This also translates into a very useful interactive documentation viewer in the form of `swagger-ui`:
![Screenshot - drf-yasg][image-drf-yasg] ![Screenshot - drf-yasg][image-drf-yasg]
#### drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework #### drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework

63
docs/topics/html-and-forms.md
View File

@ -207,14 +207,55 @@ Field templates can also use additional style properties, depending on their typ
The complete list of `base_template` options and their associated style options is listed below. The complete list of `base_template` options and their associated style options is listed below.
base_template | Valid field types | Additional style options <table border=1>
----|----|---- <tr>
input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label, autofocus <th>base_template</th>
textarea.html | `CharField` | rows, placeholder, hide_label <th>Valid field types</th>
select.html | `ChoiceField` or relational field types | hide_label <th>Additional style options</th>
radio.html | `ChoiceField` or relational field types | inline, hide_label </tr>
select_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | hide_label <tr>
checkbox_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | inline, hide_label <td>input.html</td>
checkbox.html | `BooleanField` | hide_label <td>Any string, numeric or date/time field</td>
fieldset.html | Nested serializer | hide_label <td>input_type, placeholder, hide_label, autofocus</td>
list_fieldset.html | `ListField` or nested serializer with `many=True` | hide_label </tr>
<tr>
<td>textarea.html</td>
<td><code>CharField</code></td>
<td>rows, placeholder, hide_label</td>
</tr>
<tr>
<td>select.html</td>
<td><code>ChoiceField</code> or relational field types</td>
<td>hide_label</td>
</tr>
<tr>
<td>radio.html</td>
<td><code>ChoiceField</code> or relational field types</td>
<td>inline, hide_label</td>
</tr>
<tr>
<td>select_multiple.html</td>
<td><code>MultipleChoiceField</code> or relational fields with <code>many=True</code></td>
<td>hide_label</td>
</tr>
<tr>
<td>checkbox_multiple.html</td>
<td><code>MultipleChoiceField</code> or relational fields with <code>many=True</code></td>
<td>inline, hide_label</td>
</tr>
<tr>
<td>checkbox.html</td>
<td><code>BooleanField</code></td>
<td>hide_label</td>
</tr>
<tr>
<td>fieldset.html</td>
<td>Nested serializer</td>
<td>hide_label</td>
</tr>
<tr>
<td>list_fieldset.html</td>
<td><code>ListField</code> or nested serializer with <code>many=True</code></td>
<td>hide_label</td>
</tr>
</table>

5
docs/topics/writable-nested-serializers.md
View File

@ -1,9 +1,9 @@
# Writable nested serializers
> To save HTTP requests, it may be convenient to send related documents along with the request. > To save HTTP requests, it may be convenient to send related documents along with the request.
> >
> &mdash; [JSON API specification for Ember Data][cite]. > &mdash; [JSON API specification for Ember Data][cite].
# Writable nested serializers
Although flat data structures serve to properly delineate between the individual entities in your service, there are cases where it may be more appropriate or convenient to use nested data structures. Although flat data structures serve to properly delineate between the individual entities in your service, there are cases where it may be more appropriate or convenient to use nested data structures.
Nested data structures are easy enough to work with if they're read-only - simply nest your serializer classes and you're good to go. However, there are a few more subtleties to using writable nested serializers, due to the dependencies between the various model instances, and the need to save or delete multiple instances in a single action. Nested data structures are easy enough to work with if they're read-only - simply nest your serializer classes and you're good to go. However, there are a few more subtleties to using writable nested serializers, due to the dependencies between the various model instances, and the need to save or delete multiple instances in a single action.
@ -43,5 +43,4 @@ Let's take a look at updating our nested one-to-many data structure.
### Making PATCH requests ### Making PATCH requests
[cite]: http://jsonapi.org/format/#url-based-json-api [cite]: http://jsonapi.org/format/#url-based-json-api

2
docs/tutorial/quickstart.md
View File

@ -137,6 +137,7 @@ Again, if we need more control over the API URLs we can simply drop down to usin
Finally, we're including default login and logout views for use with the browsable API. That's optional, but useful if your API requires authentication and you want to use the browsable API. Finally, we're including default login and logout views for use with the browsable API. That's optional, but useful if your API requires authentication and you want to use the browsable API.
## Pagination ## Pagination
Pagination allows you to control how many objects per page are returned. To enable it add the following lines to `tutorial/settings.py` Pagination allows you to control how many objects per page are returned. To enable it add the following lines to `tutorial/settings.py`
REST_FRAMEWORK = { REST_FRAMEWORK = {
@ -200,7 +201,6 @@ Or using the [httpie][httpie], command line tool...
] ]
} }
Or directly through the browser, by going to the URL `http://127.0.0.1:8000/users/`... Or directly through the browser, by going to the URL `http://127.0.0.1:8000/users/`...
![Quick start image][image] ![Quick start image][image]