Merge pull request #93 from Nobatek/arguments_description

Allow passing description for requestBody

flask_rest_api/arguments.py

@@ -14,7 +14,7 @@ class ArgumentsMixin:
 
     def arguments(
             self, schema, *, location='json', content_type=None, required=True,
-            example=None, examples=None, **kwargs
+            description=None, example=None, examples=None, **kwargs
     ):
         """Decorator specifying the schema used to deserialize parameters
 
@@ -28,16 +28,19 @@ def arguments(
             ``Blueprint.DEFAULT_LOCATION_CONTENT_TYPE_MAPPING``.
             This is only used for documentation purpose.
         :param bool required: Whether argument is required (default: True).
-            This only affects `body` arguments as, in this case, the docs
-            expose the whole schema as a `required` parameter.
-            For other locations, the schema is turned into an array of
-            parameters and their required value is inferred from the schema.
+        :param str description: Argument description.
         :param dict example: Parameter example.
         :param list examples: List of parameter examples.
         :param dict kwargs: Keyword arguments passed to the webargs
             :meth:`use_args <webargs.core.Parser.use_args>` decorator used
             internally.
 
+        The `required` and `description` only affect `body` arguments
+        (OpenAPI 2) or `requestBody` (OpenAPI 3), because the docs expose the
+        whole schema. For other locations, the schema is turned into an array
+        of parameters and the required/description value of each parameter item
+        is taken from the corresponding field in the schema.
+
         The `example` and `examples` parameters are mutually exclusive and
         should only be used with OpenAPI 3 and when location is ``json``.
 
@@ -56,6 +59,8 @@ def arguments(
             parameters['example'] = example
         if examples is not None:
             parameters['examples'] = examples
+        if description is not None:
+            parameters['description'] = description
 
         def decorator(func):
 

tests/test_blueprint.py

@@ -181,6 +181,57 @@ def func():
             # Only the required attribute of the field matters
             assert parameters[0]['required'] is False
 
+    @pytest.mark.parametrize('openapi_version', ('2.0', '3.0.2'))
+    @pytest.mark.parametrize('location_map', LOCATIONS_MAPPING)
+    @pytest.mark.parametrize('description', ('Description', None))
+    def test_blueprint_arguments_description(
+            self, app, schemas, description, location_map, openapi_version):
+        app.config['OPENAPI_VERSION'] = openapi_version
+        api = Api(app)
+        blp = Blueprint('test', __name__, url_prefix='/test')
+        location, _ = location_map
+
+        @blp.route('/')
+        @blp.arguments(
+            schemas.DocSchema, description=description, location=location)
+        def func():
+            pass
+
+        api.register_blueprint(blp)
+        get = api.spec.to_dict()['paths']['/test/']['get']
+        # OAS3 / json, form, files
+        if (
+                openapi_version == '3.0.2' and
+                location in REQUEST_BODY_CONTENT_TYPE
+        ):
+            # Body parameter in 'requestBody'
+            assert 'requestBody' in get
+            if description is not None:
+                assert get['requestBody']['description'] == description
+            else:
+                assert 'description' not in get['requestBody']
+        # OAS2 / json
+        elif location == 'json':
+            parameters = get['parameters']
+            # One parameter: the schema
+            assert len(parameters) == 1
+            assert 'schema' in parameters[0]
+            assert 'requestBody' not in get
+            if description is not None:
+                assert parameters[0]['description'] == description
+            else:
+                assert 'description' not in parameters[0]
+        # OAS2-3 / all
+        else:
+            parameters = get['parameters']
+            # One parameter: the 'field' field in DocSchema
+            assert len(parameters) == 1
+            assert parameters[0]['name'] == 'field'
+            assert 'requestBody' not in get
+            # Check the description parameter has no impact.
+            # Only the description attribute of the field matters
+            assert 'description' not in parameters[0]
+
     @pytest.mark.parametrize('openapi_version', ('2.0', '3.0.2'))
     def test_blueprint_arguments_multiple(self, app, schemas, openapi_version):
         app.config['OPENAPI_VERSION'] = openapi_version