Version 3.5

.travis.yml

@@ -14,7 +14,6 @@ env:
     - TOX_ENV=py35-django18
     - TOX_ENV=py34-django18
     - TOX_ENV=py33-django18
-    - TOX_ENV=py32-django18
     - TOX_ENV=py27-django18
     - TOX_ENV=py27-django110
     - TOX_ENV=py35-django110

docs/api-guide/filtering.md

@@ -416,6 +416,12 @@ Generic filters may also present an interface in the browsable API. To do so you
 
 The method should return a rendered HTML string.
 
+## Pagination & schemas
+
+You can also make the filter controls available to the schema autogeneration
+that REST framework provides, by implementing a `get_schema_fields()` method,
+which should return a list of `coreapi.Field` instances.
+
 # Third party packages
 
 The following third party packages provide additional filter implementations.

docs/api-guide/pagination.md

@@ -276,6 +276,12 @@ To have your custom pagination class be used by default, use the `DEFAULT_PAGINA
 
 API responses for list endpoints will now include a `Link` header, instead of including the pagination links as part of the body of the response, for example:
 
+## Pagination & schemas
+
+You can also make the pagination controls available to the schema autogeneration
+that REST framework provides, by implementing a `get_schema_fields()` method,
+which should return a list of `coreapi.Field` instances.
+
 ---
 
 ![Link Header][link-header]

docs/api-guide/relations.md

@@ -457,6 +457,8 @@ There are two keyword arguments you can use to control this behavior:
 - `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to `None` to disable any limiting. Defaults to `1000`.
 - `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
 
+You can also control these globally using the settings `HTML_SELECT_CUTOFF` and `HTML_SELECT_CUTOFF_TEXT`.
+
 In cases where the cutoff is being enforced you may want to instead use a plain input field in the HTML form. You can do so using the `style` keyword argument. For example:
 
     assigned_to = serializers.SlugRelatedField(

docs/api-guide/reverse.md

@@ -23,7 +23,7 @@ There's no requirement for you to use them, but if you do then the self-describi
 
 **Signature:** `reverse(viewname, *args, **kwargs)`
 
-Has the same behavior as [`django.core.urlresolvers.reverse`][reverse], except that it returns a fully qualified URL, using the request to determine the host and port.
+Has the same behavior as [`django.urls.reverse`][reverse], except that it returns a fully qualified URL, using the request to determine the host and port.
 
 You should **include the request as a keyword argument** to the function, for example:
 
@@ -44,7 +44,7 @@ You should **include the request as a keyword argument** to the function, for ex
 
 **Signature:** `reverse_lazy(viewname, *args, **kwargs)`
 
-Has the same behavior as [`django.core.urlresolvers.reverse_lazy`][reverse-lazy], except that it returns a fully qualified URL, using the request to determine the host and port.
+Has the same behavior as [`django.urls.reverse_lazy`][reverse-lazy], except that it returns a fully qualified URL, using the request to determine the host and port.
 
 As with the `reverse` function, you should **include the request as a keyword argument** to the function, for example:
 

docs/api-guide/schemas.md

@@ -102,15 +102,20 @@ REST framework includes functionality for auto-generating a schema,
 or allows you to specify one explicitly. There are a few different ways to
 add a schema to your API, depending on exactly what you need.
 
-## Using DefaultRouter
+## The get_schema_view shortcut
 
-If you're using `DefaultRouter` then you can include an auto-generated schema,
-simply by adding a `schema_title` argument to the router.
+The simplest way to include a schema in your project is to use the
+`get_schema_view()` function.
 
-    router = DefaultRouter(schema_title='Server Monitoring API')
+    schema_view = get_schema_view(title="Server Monitoring API")
 
-The schema will be included at the root URL, `/`, and presented to clients
-that include the Core JSON media type in their `Accept` header.
+    urlpatterns = [
+        url('^$', schema_view),
+        ...
+    ]
+
+Once the view has been added, you'll be able to make API requests to retrieve
+the auto-generated schema definition.
 
     $ http http://127.0.0.1:8000/ Accept:application/vnd.coreapi+json
     HTTP/1.0 200 OK
@@ -125,48 +130,43 @@ that include the Core JSON media type in their `Accept` header.
         ...
     }
 
-This is a great zero-configuration option for when you want to get up and
-running really quickly.
-
-The other available options to `DefaultRouter` are:
+The arguments to `get_schema_view()` are:
 
-#### schema_renderers
-
-May be used to pass the set of renderer classes that can be used to render schema output.
-
-    from rest_framework.renderers import CoreJSONRenderer
-    from my_custom_package import APIBlueprintRenderer
+#### `title`
 
-    router = DefaultRouter(schema_title='Server Monitoring API', schema_renderers=[
-        CoreJSONRenderer, APIBlueprintRenderer
-    ])
+May be used to provide a descriptive title for the schema definition.
 
-#### schema_url
+#### `url`
 
-May be used to pass the root URL for the schema. This can either be used to ensure that
-the schema URLs include a canonical hostname and schema, or to ensure that all the
-schema URLs include a path prefix.
+May be used to pass a canonical URL for the schema.
 
-    router = DefaultRouter(
-        schema_title='Server Monitoring API',
-        schema_url='https://www.example.org/api/'
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/'
     )
 
-If you want more flexibility over the schema output then you'll need to consider
-using `SchemaGenerator` instead.
-
-#### root_renderers
+#### `renderer_classes`
 
 May be used to pass the set of renderer classes that can be used to render the API root endpoint.
 
-## Using SchemaGenerator
+    from rest_framework.renderers import CoreJSONRenderer
+    from my_custom_package import APIBlueprintRenderer
 
-The most common way to add a schema to your API is to use the `SchemaGenerator`
-class to auto-generate the `Document` instance, and to return that from a view.
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/',
+        renderer_classes=[CoreJSONRenderer, APIBlueprintRenderer]
+    )
+
+## Using an explicit schema view
+
+If you need a little more control than the `get_schema_view()` shortcut gives you,
+then you can use the `SchemaGenerator` class directly to auto-generate the
+`Document` instance, and to return that from a view.
 
 This option gives you the flexibility of setting up the schema endpoint
-with whatever behavior you want. For example, you can apply different
-permission, throttling or authentication policies to the schema endpoint.
+with whatever behaviour you want. For example, you can apply different
+permission, throttling, or authentication policies to the schema endpoint.
 
 Here's an example of using `SchemaGenerator` together with a view to
 return the schema.
@@ -176,12 +176,13 @@ return the schema.
     from rest_framework.decorators import api_view, renderer_classes
     from rest_framework import renderers, response, schemas
 
+    generator = schemas.SchemaGenerator(title='Bookings API')
 
     @api_view()
     @renderer_classes([renderers.CoreJSONRenderer])
     def schema_view(request):
-        generator = schemas.SchemaGenerator(title='Bookings API')
-        return response.Response(generator.get_schema())
+        schema = generator.get_schema(request)
+        return response.Response(schema)
 
 **urls.py:**
 
@@ -241,6 +242,69 @@ You could then either:
 
 ---
 
+# Schemas as documentation
+
+One common usage of API schemas is to use them to build documentation pages.
+
+The schema generation in REST framework uses docstrings to automatically
+populate descriptions in the schema document.
+
+These descriptions will be based on:
+
+* The corresponding method docstring if one exists.
+* A named section within the class docstring, which can be either single line or multi-line.
+* The class docstring.
+
+## Examples
+
+An `APIView`, with an explicit method docstring.
+
+    class ListUsernames(APIView):
+        def get(self, request):
+            """
+            Return a list of all user names in the system.
+            """
+            usernames = [user.username for user in User.objects.all()]
+            return Response(usernames)
+
+A `ViewSet`, with an explict action docstring.
+
+    class ListUsernames(ViewSet):
+        def list(self, request):
+            """
+            Return a list of all user names in the system.
+            """
+            usernames = [user.username for user in User.objects.all()]
+            return Response(usernames)
+
+A generic view with sections in the class docstring, using single-line style.
+
+    class UserList(generics.ListCreateAPIView):
+        """
+        get: Create a new user.
+        post: List all the users.
+        """
+        queryset = User.objects.all()
+        serializer_class = UserSerializer
+        permission_classes = (IsAdminUser,)
+
+A generic viewset with sections in the class docstring, using multi-line style.
+
+    class UserViewSet(viewsets.ModelViewSet):
+        """
+        API endpoint that allows users to be viewed or edited.
+
+        retrieve:
+        Return a user instance.
+
+        list:
+        Return all users, ordered by most recently joined.
+        """
+        queryset = User.objects.all().order_by('-date_joined')
+        serializer_class = UserSerializer
+
+---
+
 # Alternate schema formats
 
 In order to support an alternate schema format, you need to implement a custom renderer

docs/api-guide/settings.md

@@ -234,6 +234,28 @@ Default:
 
 ---
 
+## Schema generation controls
+
+#### SCHEMA_COERCE_PATH_PK
+
+If set, this maps the `'pk'` identifier in the URL conf onto the actual field
+name when generating a schema path parameter. Typically this will be `'id'`.
+This gives a more suitable representation as "primary key" is an implementation
+detail, wheras "identifier" is a more general concept.
+
+Default: `True`
+
+#### SCHEMA_COERCE_METHOD_NAMES
+
+If set, this is used to map internal viewset method names onto external action
+names used in the schema generation. This allows us to generate names that
+are more suitable for an external representation than those that are used
+internally in the codebase.
+
+Default: `{'retrieve': 'read', 'destroy': 'delete'}`
+
+---
+
 ## Content type controls
 
 #### URL_FORMAT_OVERRIDE
@@ -382,6 +404,22 @@ This should be a function with the following signature:
 
 Default: `'rest_framework.views.get_view_description'`
 
+## HTML Select Field cutoffs
+
+Global settings for [select field cutoffs for rendering relational fields](relations.md#select-field-cutoffs) in the browsable API.
+
+#### HTML_SELECT_CUTOFF
+
+Global setting for the `html_cutoff` value.  Must be an integer.
+
+Default: 1000
+
+#### HTML_SELECT_CUTOFF_TEXT
+
+A string representing a global setting for `html_cutoff_text`.
+
+Default: `"More than {count} items..."`
+
 ---
 
 ## Miscellaneous settings