Support envelope parameter in Swagger documentation

fix #390
noirbizarre · Jul 19, 2019 · e9b5459 · e9b5459
1 parent fe085c8
commit e9b5459
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 3 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -12,6 +12,7 @@ Current
 - Ensure `basePath` is always a path
 - Hide Namespaces with all hidden Resources from Swagger documentation
 - Per route Swagger documentation for multiple routes on a ``Resource``
+- Support ``envelope`` parameter in Swagger documentation (:pr:`390`)
 
 0.12.1 (2018-09-28)
 -------------------

diff --git a/flask_restplus/namespace.py b/flask_restplus/namespace.py
@@ -238,7 +238,7 @@ def marshal_with(self, fields, as_list=False, code=HTTPStatus.OK, description=No
         def wrapper(func):
             doc = {
                 'responses': {
-                    code: (description, [fields]) if as_list else (description, fields)
+                    code: (description, [fields], kwargs) if as_list else (description, fields, kwargs)
                 },
                 '__mask__': kwargs.get('mask', True),  # Mask values can't be determined outside app context
             }

diff --git a/flask_restplus/swagger.py b/flask_restplus/swagger.py
@@ -368,7 +368,7 @@ def register_errors(self):
             apidoc = getattr(handler, '__apidoc__', {})
             self.process_headers(response, apidoc)
             if 'responses' in apidoc:
-                _, model = list(apidoc['responses'].values())[0]
+                _, model, _ = list(apidoc['responses'].values())[0]
                 response['schema'] = self.serialize_schema(model)
             responses[exception.__name__] = not_none(response)
         return responses
@@ -502,7 +502,11 @@ def responses_for(self, doc, method):
                     else:
                         responses[code] = {'description': description}
                     if model:
-                        responses[code]['schema'] = self.serialize_schema(model)
+                        schema = self.serialize_schema(model)
+                        envelope = kwargs.get('envelope')
+                        if envelope:
+                            schema = {'properties': {envelope: schema}}
+                        responses[code]['schema'] = schema
                     self.process_headers(responses[code], doc, method, kwargs.get('headers'))
             if 'model' in d:
                 code = str(d.get('default_code', HTTPStatus.OK))

diff --git a/tests/test_swagger.py b/tests/test_swagger.py
@@ -1725,6 +1725,38 @@ def get(self):
             }
         }
 
+    def test_marhsal_decorator_with_envelope(self, api, client):
+        person = api.model('Person', {
+            'name': restplus.fields.String,
+            'age': restplus.fields.Integer,
+            'birthdate': restplus.fields.DateTime,
+        })
+
+        @api.route('/model-as-dict/')
+        class ModelAsDict(restplus.Resource):
+            @api.marshal_with(person, envelope='person')
+            def get(self):
+                return {}
+
+        data = client.get_specs()
+
+        assert 'definitions' in data
+        assert 'Person' in data['definitions']
+
+        responses = data['paths']['/model-as-dict/']['get']['responses']
+        assert responses == {
+            '200': {
+                'description': 'Success',
+                'schema': {
+                    'properties': {
+                        'person': {
+                            '$ref': '#/definitions/Person'
+                        }
+                    }
+                }
+            }
+        }
+
     def test_model_as_flat_dict_with_marchal_decorator_list(self, api, client):
         fields = api.model('Person', {
             'name': restplus.fields.String,