Ensure definitions with both and description (or other property) output is valid (using )

Author: noirbizarre

CHANGELOG.rst

@@ -7,6 +7,7 @@ Current
 -------
 
 - Fix missing changelog inprevious release
+- Ensure definitions with both `$ref` and description (or other property) output is valid (using `allOf`)
 
 0.12.0 (2018-09-27)
 -------------------

flask_restplus/fields.py

@@ -227,11 +227,13 @@ def schema(self):
         if self.as_list:
             schema['type'] = 'array'
             schema['items'] = {'$ref': ref}
+        elif any(schema.values()):
+            # There is already some properties in the schema
+            allOf = schema.get('allOf', [])
+            allOf.append({'$ref': ref})
+            schema['allOf'] = allOf
         else:
             schema['$ref'] = ref
-            # if not self.allow_null and not self.readonly:
-            #     schema['required'] = True
-
         return schema
 
     def clone(self, mask=None):

tests/test_swagger.py

@@ -1517,9 +1517,6 @@ def test_model_as_nested_dict(self, api, client):
         })
 
         fields = api.model('Person', {
-            'name': restplus.fields.String,
-            'age': restplus.fields.Integer,
-            'birthdate': restplus.fields.DateTime,
             'address': restplus.fields.Nested(address_fields)
         })
 
@@ -1537,8 +1534,16 @@ def post(self):
 
         assert 'definitions' in data
         assert 'Person' in data['definitions']
+        assert data['definitions']['Person'] == {
+            'properties': {
+                'address': {
+                    '$ref': '#/definitions/Address'
+                },
+            },
+            'type': 'object'
+        }
 
-        assert 'Address' in data['definitions'].keys()
+        assert 'Address' in data['definitions']
         assert data['definitions']['Address'] == {
             'properties': {
                 'road': {
@@ -1552,6 +1557,50 @@ def post(self):
         assert path['get']['responses']['200']['schema']['$ref'] == '#/definitions/Person'
         assert path['post']['responses']['200']['schema']['$ref'] == '#/definitions/Person'
 
+    def test_model_as_nested_dict_with_details(self, api, client):
+        address_fields = api.model('Address', {
+            'road': restplus.fields.String,
+        })
+
+        fields = api.model('Person', {
+            'address': restplus.fields.Nested(address_fields, description='description', readonly=True)
+        })
+
+        @api.route('/model-as-dict/')
+        class ModelAsDict(restplus.Resource):
+            @api.doc(model=fields)
+            def get(self):
+                return {}
+
+            @api.doc(model='Person')
+            def post(self):
+                return {}
+
+        data = client.get_specs()
+
+        assert 'definitions' in data
+        assert 'Person' in data['definitions']
+        assert data['definitions']['Person'] == {
+            'properties': {
+                'address': {
+                    'description': 'description',
+                    'readOnly': True,
+                    'allOf': [{'$ref': '#/definitions/Address'}]
+                },
+            },
+            'type': 'object'
+        }
+
+        assert 'Address' in data['definitions']
+        assert data['definitions']['Address'] == {
+            'properties': {
+                'road': {
+                    'type': 'string'
+                },
+            },
+            'type': 'object'
+        }
+
     def test_model_as_flat_dict_with_marchal_decorator(self, api, client):
         fields = api.model('Person', {
             'name': restplus.fields.String,