Add documentation about excluding endpoints

Closes #50.

docs/custom_spec.rst

@@ -9,6 +9,31 @@ Custom schema generation
 If the default spec generation does not quite match what you were hoping to achieve, ``drf-yasg`` provides some
 custom behavior hooks by default.
 
+.. _custom-spec-excluding-endpoints:
+
+*******************
+Excluding endpoints
+*******************
+
+You can prevent a view from being included in the Swagger view by setting its class-level ``swagger_schema``
+attribute to ``None``, or you can prevent an operation from being included by setting its ``auto_schema`` override
+to none in :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`:
+
+.. code-block:: python
+
+   class UserList(APIView):
+      swagger_schema = None
+
+      # all methods of the UserList class will be excluded
+      ...
+
+   # only the GET method will be shown in Swagger
+   @swagger_auto_schema(method='put', auto_schema=None)
+   @swagger_auto_schema(methods=['get'], ...)
+   @api_view(['GET', 'PUT'])
+   def user_detail(request, pk):
+      pass
+
 .. _custom-spec-swagger-auto-schema:
 
 **************************************
@@ -200,8 +225,6 @@ This custom generator can be put to use by setting it as the :attr:`.generator_c
 ``Inspector`` classes
 ---------------------
 
-.. versionadded:: 1.1
-
 For customizing behavior related to specific field, serializer, filter or paginator classes you can implement the
 :class:`~.inspectors.FieldInspector`, :class:`~.inspectors.SerializerInspector`, :class:`~.inspectors.FilterInspector`,
 :class:`~.inspectors.PaginatorInspector` classes and use them with

docs/openapi.rst

@@ -6,7 +6,6 @@
 Functional overview
 **********************
 
-
 ------------------------------
 OpenAPI specification overview
 ------------------------------
@@ -155,9 +154,26 @@ This section describes where information is sourced from when using the default
 
   Other versioning schemes are not presently supported.
 
+---------------------
+A note on limitations
+---------------------
 
-.. versionadded:: 1.2
-   Base path and versioning support.
+When schema generation is requested, available endpoints are inspected by enumeration all the routes registered in
+Django's urlconf. Each registered view is then artificially instantiated for introspection, and it is this step that
+brings some limitations to what can be done:
+
+* the ``request`` the view sees will always be the request made against the schema view endpoint
+  - e.g. ``GET /swagger.yaml``
+* path parameters will not be filled
+
+This means that you could get surprizing results if your ``get_serializer`` or ``get_serializer_class`` methods
+depend on the incoming request, call ``get_object`` or in general depend on any stateful logic. You can prevent this
+in a few ways:
+
+* provide a fixed serializer for request and response body introspection using
+  :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`, to prevent ``get_serializer`` from being called on
+  the view
+* :ref:`exclude your endpoint from introspection <custom-spec-excluding-endpoints>`
 
 .. _SCRIPT_NAME: https://www.python.org/dev/peps/pep-0333/#environ-variables
 .. _FORCE_SCRIPT_NAME: https://docs.djangoproject.com/en/2.0/ref/settings/#force-script-name

docs/rendering.rst

@@ -41,8 +41,6 @@ You can use your custom renderer classes as kwargs to :meth:`.SchemaView.as_cach
 Management command
 ******************
 
-.. versionadded:: 1.1.1
-
 If you only need a swagger spec file in YAML or JSON format, you can use the ``generate_swagger`` management command
 to get it without having to start the web server: