Update documentation about Responses and form data

docs/custom_spec.rst

@@ -50,9 +50,27 @@ is structured, starting from the root ``Swagger`` object.
    + ``operationId`` - should be unique across all operations
    + ``tags`` - used to group operations in the listing
 
-It is interesting to note that the main difference between ``Parameter`` and ``Schema`` is that Schemas can nest other
+It is interesting to note the main differences between :class:`.Parameter` and :class:`.Schema` objects:
-Schemas, while Parameters are "primitives" and cannot contain other Parameters. The only exception are ``body``
+
-Parameters, which can contain a Schema.
++----------------------------------------------------------+-----------------------------------------------------------+
+| :class:`.Schema`                                         | :class:`.Parameter`                                       |
++==========================================================+===========================================================+
+| Can nest other Schemas                                   | Cannot nest other Parameters |br|                         |
+|                                                          | Can only nest a Schema if the parameter is ``in: body``   |
++----------------------------------------------------------+-----------------------------------------------------------+
+| Cannot describe file uploads |br|                        | Can describe file uploads via ``type`` = ``file``, |br|   |
+| - ``file`` is not permitted as a value for ``type``      | but only as part of a form :class:`.Operation` [#formop]_ |
++----------------------------------------------------------+-----------------------------------------------------------+
+| Can be used in :class:`.Response`\ s                     | Cannot be used in :class:`.Response`\ s                   |
++----------------------------------------------------------+-----------------------------------------------------------+
+| Cannot be used in form :class:`.Operation`\ s [#formop]_ | Can be used in form :class:`.Operation`\ s [#formop]_     |
++----------------------------------------------------------+-----------------------------------------------------------+
+
+.. [#formop] a form Operation is an :class:`.Operation` that consumes ``multipart/form-data`` or
+   ``application/x-www-form-urlencoded``
+
+      * a form Operation cannot have ``body`` parameters
+      * a non-form operation cannot have ``form`` parameters
 
 **************************************
 The ``@swagger_auto_schema`` decorator

src/drf_yasg/openapi.py

@@ -48,8 +48,8 @@ def make_swagger_name(attribute_name):
     Convert a python variable name into a Swagger spec attribute name.
 
     In particular,
-     * if name starts with x\_, return "x-{camelCase}"
+     * if name starts with ``x_``, return ``x-{camelCase}``
-     * if name is 'ref', return "$ref"
+     * if name is ``ref``, return ``$ref``
      * else return the name converted to camelCase, with trailing underscores stripped
 
     :param str attribute_name: python attribute name
@@ -64,7 +64,10 @@ def make_swagger_name(attribute_name):
 
 class SwaggerDict(OrderedDict):
     """A particular type of OrderedDict, which maps all attribute accesses to dict lookups using
-     :func:`.make_swagger_name`.  Used as a base class for all Swagger helper models.
+     :func:`.make_swagger_name`. Attribute names starting with ``_`` are set on the object as-is and are not included
+     in the specification output.
+
+     Used as a base class for all Swagger helper models.
     """
 
     def __init__(self, **attrs):