Correctly specify a JSON request body payload as a single schema

Currently, a JSON object payload is treated as a collection of separate
parameters and specified as a list of schema in the generated Swagger
spec. This commit changes this behaviour to comply with
https://swagger.io/docs/specification/2-0/describing-request-body/ where
object payloads are specified using a single schema encapsulation all
the properties.

Author: tnweiss

flask_restx/swagger.py

@@ -148,6 +148,48 @@ def is_hidden(resource, route_doc=None):
         return hasattr(resource, "__apidoc__") and resource.__apidoc__ is False
 
 
+def build_request_body_parameters_schema(body_params):
+    """
+    :param body_params: List of JSON schema of body parameters.
+    :type body_params: list of dict, generated from the json body parameters of a request parser
+    :return dict: The Swagger schema representation of the request body
+
+    :Example:
+        {
+            'name': 'payload',
+            'required': True,
+            'in': 'body',
+            'schema': {
+                'type': 'object',
+                'properties': [
+                    'parameter1': {
+                        'type': 'integer'
+                    },
+                    'parameter2': {
+                        'type': 'string'
+                    }
+                ]
+            }
+        }
+    """
+
+    properties = {}
+    for param in body_params:
+        properties[param['name']] = {
+            'type': param.get('type', 'string')
+        }
+
+    return {
+        'name': 'payload',
+        'required': True,
+        'in': 'body',
+        'schema': {
+            'type': 'object',
+            'properties': properties
+        }
+    }
+
+
 class Swagger(object):
     '''
     A Swagger documentation wrapper for an API instance.
@@ -334,8 +376,12 @@ def expected_params(self, doc):
 
         for expect in doc.get('expect', []):
             if isinstance(expect, RequestParser):
-                parser_params = OrderedDict((p['name'], p) for p in expect.__schema__)
+                parser_params = OrderedDict((p['name'], p) for p in expect.__schema__ if p['in'] != 'body')
                 params.update(parser_params)
+
+                body_params = [p for p in expect.__schema__ if p['in'] == 'body']
+                if body_params:
+                    params['payload'] = build_request_body_parameters_schema(body_params)
             elif isinstance(expect, ModelBase):
                 params['payload'] = not_none({
                     'name': 'payload',

tests/test_swagger.py

@@ -623,6 +623,7 @@ def get(self, age):
     def test_expect_parser(self, api, client):
         parser = api.parser()
         parser.add_argument('param', type=int, help='Some param')
+        parser.add_argument('jsonparam', type=str, location='json', help='Some param')
 
         @api.route('/with-parser/', endpoint='with-parser')
         class WithParserResource(restx.Resource):
@@ -634,14 +635,20 @@ def get(self):
         assert '/with-parser/' in data['paths']
 
         op = data['paths']['/with-parser/']['get']
-        assert len(op['parameters']) == 1
+        assert len(op['parameters']) == 2
 
-        parameter = op['parameters'][0]
+        parameter = [o for o in op['parameters'] if o['in'] == 'query'][0]
         assert parameter['name'] == 'param'
         assert parameter['type'] == 'integer'
         assert parameter['in'] == 'query'
         assert parameter['description'] == 'Some param'
 
+        parameter = [o for o in op['parameters'] if o['in'] == 'body'][0]
+        assert parameter['name'] == 'payload'
+        assert parameter['required']
+        assert parameter['in'] == 'body'
+        assert parameter['schema']['properties']['jsonparam']['type'] == 'string'
+
     def test_expect_parser_on_class(self, api, client):
         parser = api.parser()
         parser.add_argument('param', type=int, help='Some param')
@@ -3377,3 +3384,19 @@ def post(self):
 
         assert 'body' not in ModelAsDict.post.__apidoc__
         assert ModelAsDict.post.__apidoc__['expect'] == [(fields, 'Body description')]
+
+    def test_build_request_body_parameters_schema(self):
+        parser = restx.reqparse.RequestParser()
+        parser.add_argument('test', type=int, location='headers')
+        parser.add_argument('test1', type=int, location='json')
+        parser.add_argument('test2', location='json')
+
+        body_params = [p for p in parser.__schema__ if p['in'] == 'body']
+        result = restx.swagger.build_request_body_parameters_schema(body_params)
+
+        assert result['name'] == 'payload'
+        assert result['required']
+        assert result['in'] == 'body'
+        assert result['schema']['type'] == 'object'
+        assert result['schema']['properties']['test1']['type'] == 'integer'
+        assert result['schema']['properties']['test2']['type'] == 'string'