Add query_serializer argument to swagger_auto_schema (#17)

Closes #16.
2017-12-16 15:37:42 +01:00
parent bdf7e8a4ae
commit 73bd7a136d
9 changed files with 190 additions and 37 deletions
@@ -196,6 +196,7 @@ nitpick_ignore = [
    ('py:obj', 'APIView'),
 ]

+sys.path.insert(0, os.path.abspath('../src'))
 sys.path.insert(0, os.path.abspath('../testproj'))
 os.putenv('DJANGO_SETTINGS_MODULE', 'testproj.settings')

@@ -208,8 +209,8 @@ import drf_yasg.views  # noqa: E402
 # instantiate a SchemaView in the views module to make it available to autodoc
 drf_yasg.views.SchemaView = drf_yasg.views.get_schema_view(None)

-ghiss_uri = "https://github.com/axnsan12/drf-yasg/issues/%d"
-ghpr_uri = "https://github.com/axnsan12/drf-yasg/pull/%d"
+gh_issue_uri = "https://github.com/axnsan12/drf-yasg/issues/%d"
+gh_pr_uri = "https://github.com/axnsan12/drf-yasg/pull/%d"


 def role_github_pull_request_or_issue(name, rawtext, text, lineno, inliner, options=None, content=None):
@@ -229,9 +230,9 @@ def role_github_pull_request_or_issue(name, rawtext, text, lineno, inliner, opti
        # Base URL mainly used by inliner.rfc_reference, so this is correct:

    if name == 'pr':
-        ref = ghpr_uri
+        ref = gh_pr_uri
    elif name == 'issue':
-        ref = ghiss_uri
+        ref = gh_issue_uri
    else:
        msg = inliner.reporter.error('unknown tag name for GitHub reference - "%s"' % name, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
@@ -65,13 +65,72 @@ It is interesting to note the main differences between :class:`.Parameter` and :
 +----------------------------------------------------------+-----------------------------------------------------------+
 | Cannot be used in form :class:`.Operation`\ s [#formop]_ | Can be used in form :class:`.Operation`\ s [#formop]_     |
 +----------------------------------------------------------+-----------------------------------------------------------+
+| Can only describe request or response bodies             | Can describe ``query``, ``form``, ``header`` or ``path``  |
+|                                                          | parameters                                                |
+----------------------------------------------------------+-----------------------------------------------------------+

 .. [#formop] a form Operation is an :class:`.Operation` that consumes ``multipart/form-data`` or
-   ``application/x-www-form-urlencoded``
+   ``application/x-www-form-urlencoded`` content

      * a form Operation cannot have ``body`` parameters
      * a non-form operation cannot have ``form`` parameters

+****************
+Default behavior
+****************
+
+This section describes where information is sourced from when using the default generation process.
+
+* :class:`.Paths` are generated by exploring the patterns registered in your default ``urlconf``, or the ``patterns``
+  and ``urlconf`` you specified when constructing :class:`.OpenAPISchemaGenerator`; only views inheriting from Django
+  Rest Framework's ``APIView`` are looked at, all other views are ignored
+* ``path`` :class:`.Parameter`\ s are generated by looking in the URL pattern for any template parameters; attempts are
+  made to guess their type from the views ``queryset`` and ``lookup_field``, if applicable. You can override path
+  parameters via ``manual_parameters`` in :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`.
+* ``query`` :class:`.Parameter`\ s - i.e. parameters specified in the URL as ``/path/?query1=value&query2=value`` -
+  are generated from your view's ``filter_backends`` and ``paginator``, if any are declared. Additional parameters can
+  be specified via the ``query_serializer`` and ``manual_parameters`` arguments of
+  :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`
+* The request body is only generated for the HTTP ``POST``, ``PUT`` and ``PATCH`` methods, and is sourced from the
+  view's ``serializer_class``. You can also override the request body using the ``request_body`` argument of
+  :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>`.
+
+   - if the view represents a form request (that is, all its parsers are of the ``multipart/form-data`` or
+     ``application/x-www-form-urlencoded`` media types), the request body will be output as ``form``
+     :class:`.Parameter`\ s
+   - if it is not a form request, the request body will be output as a single ``body`` :class:`.Parameter` wrapped
+     around a :class:`.Schema`
+
+* ``header`` :class:`.Parameter`\ s are supported by the OpenAPI specification but are never generated by this library;
+  you can still add them using ``manual_parameters``.
+* :class:`.Responses` are generated as follows:
+
+   + if ``responses`` is provided to :ref:`@swagger_auto_schema <custom-spec-swagger-auto-schema>` and contains at least
+     one success status code (i.e. any `2xx` status code), no automatic response is generated and the given response
+     is used as described in the :func:`@swagger_auto_schema documentation <.swagger_auto_schema>`
+   + otherwise, an attempt is made to generate a default response:
+
+      - the success status code is assumed to be ``204` for ``DELETE`` requests, ``201`` for ``POST`` requests, and
+        ``200`` for all other request methods
+      - if the view has a request body, the same ``Serializer`` or :class:`.Schema` as in the request body is used
+        in generating the :class:`.Response` schema; this is inline with the default ``GenericAPIView`` and
+        ``GenericViewSet`` behavior
+      - if the view has no request body, its ``serializer_class`` is used to generate the :class:`.Response` schema
+      - if the view is a list view (as defined by :func:`.is_list_view`), the response schema is wrapped in an array
+      - if the view is also paginated, the response schema is then wrapped in the appropriate paging response structure
+      - the description of the response is left blank
+
+* :class:`.Response` headers are supported by the OpenAPI specification but not currently supported by this library;
+  you can still add them manually by providing an `appropriately structured dictionary
+  <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#headersObject>`_
+  to the ``headers`` property of a :class:`.Response` object
+* *descriptions* for :class:`.Operation`\ s, :class:`.Parameter`\ s and :class:`.Schema`\ s are picked up from
+  docstrings and ``help_text`` attributes in the same manner as the `default DRF SchemaGenerator
+  <http://www.django-rest-framework.org/api-guide/schemas/#schemas-as-documentation>`_
+
+
+.. _custom-spec-swagger-auto-schema:
+
 **************************************
 The ``@swagger_auto_schema`` decorator
 **************************************