Docs: response content_type and file response

docs/response.rst

@@ -62,7 +62,7 @@ If a view function returns a list of objects, the :class:`Schema
 .. _document-alternative-responses:
 
 Documenting Alternative Responses
-=================================
+---------------------------------
 
 The :meth:`Blueprint.response <Blueprint.response>` decorator is meant to
 generate and document the response corresponding to the "normal" flow of the
@@ -84,3 +84,33 @@ used for error conditions that trigger an exception aborting the function.
 
 A view function may only be decorated once with ``response`` but can be
 decorated multiple times with nested ``alt_response``.
+
+Content Type
+------------
+
+The content type of all responses is documented by default as ``application/json``.
+
+This value can be overridden in each resource by passing another content type
+as ``content_type`` argument in :meth:`Blueprint.response <Blueprint.response>`
+and :meth:`Blueprint.response <Blueprint.alt_response>`.
+
+.. note:: The content type is only used for documentation purpose and has no
+   impact on response serialization.
+
+File Response
+-------------
+
+A file response can be documented by passing the documentation schema in its
+dict representation to :meth:`Blueprint.response <Blueprint.response>`:
+
+.. code-block:: python
+
+    @blp.route("/")
+    @blp.response(
+        200, {"format": "binary", "type": "string"}, content_type="application/csv"
+    )
+    def func():
+        csv_str = ...
+        response = Response(csv_str, mimetype="text/csv")
+        response.headers.set("Content-Disposition", "attachment", filename="file.csv")
+        return response

flask_smorest/response.py

@@ -37,7 +37,8 @@ def response(
 
         :param int|str|HTTPStatus status_code: HTTP status code.
             Used if none is returned from the view function.
-        :param schema: :class:`Schema <marshmallow.Schema>` class or instance.
+        :param schema schema|str|dict: :class:`Schema <marshmallow.Schema>`
+            class or instance or reference or dict.
             If not None, will be used to serialize response data.
         :param str content_type: Content type of the response.
         :param str description: Description of the response (default: None).
@@ -52,6 +53,8 @@ def response(
 
         If the decorated function returns a ``Response`` object, the ``schema``
         and ``status_code`` parameters are only used to document the resource.
+        Only in this case, ``schema`` may be a reference as string or a schema
+        definition as dict.
 
         The `example` and `examples` parameters are mutually exclusive. The
         latter should only be used with OpenAPI 3.
@@ -147,8 +150,8 @@ def alt_response(
 
         :param int|str|HTTPStatus status_code: HTTP status code.
         :param str response: Reponse reference.
-        :param schema schema|str: :class:`Schema <marshmallow.Schema>`
-            class or instance or reference.
+        :param schema schema|str|dict: :class:`Schema <marshmallow.Schema>`
+            class or instance or reference or dict.
         :param str description: Description of the response (default: None).
         :param dict example: Example of response message.
         :param dict examples: Examples of response message.