Optimise dereference + add warn

lib/components/base.js

@@ -117,22 +117,36 @@ export class BaseComponent {
             title: resolved.title
           };
         }
-        resolved.title = resolved.title || baseName;
-        Object.assign(schema, resolved);
+
         dereferencedCache[schema.$ref] = true;
-        delete schema.$ref;
+
+        resolved.title = resolved.title || baseName;
+
+        let keysCount = Object.keys(schema).length;
+        if ( keysCount > 2 || (keysCount === 2 && !schema.description) ) {
+          // allow only description field on the same level as $ref because it is
+          // common pattern over specs in the wild
+          console.warn(`other properties defined at the same level as $ref at '${this.pointer}'.
+            They are IGNORRED according to JsonSchema spec`);
+        }
+
+        schema = schema.description ? {
+          description: schema.description
+        } : {};
+        //for (var prop in schema) delete schema[prop];
+        Object.assign(schema, resolved);
       }
 
       Object.keys(schema).forEach((key) => {
         let value = schema[key];
         if (value && typeof value === 'object') {
-          resolve(value);
+          schema[key] = resolve(value);
         }
       });
+      return schema;
     };
 
-    resolve(schema);
-    this.componentSchema = schema;
+    this.componentSchema = resolve(schema);
   }
 
   joinAllOf(schema = this.componentSchema, opts) {

lib/components/base.spec.js

@@ -130,6 +130,28 @@ describe('Redoc components', () => {
           paramWithRef.items.schema.title.should.be.equal('Circular');
         });
       });
+
+      describe('$ref with other fields on the same level', () => {
+        let paramWithRef;
+        beforeAll(() => {
+          component.pointer = '/paths/test5/get';
+          component.ngOnInit();
+          component.dereference();
+          paramWithRef = component.componentSchema.parameters[0];
+        });
+
+        it('should skip other fields', () => {
+          expect(paramWithRef.$ref).toBeUndefined();
+          expect(paramWithRef.title).toBeDefined();
+          paramWithRef.title.should.be.equal('Simple');
+        });
+
+        it('should preserve description field', () => {
+          expect(paramWithRef.$ref).toBeUndefined();
+          expect(paramWithRef.description).toBeDefined();
+          paramWithRef.description.should.be.equal('test');
+        });
+      });
     });
 
     describe('mergeAllOf', () => {

tests/schemas/base-component-dereference.json

@@ -81,6 +81,18 @@
           }
         ]
       }
+    },
+    "test5": {
+      "get": {
+        "summary": "test get",
+        "parameters": [
+          {
+            "$ref": "#/definitions/Simple",
+            "title": "test",
+            "description": "test"
+          }
+        ]
+      }
     }
   }
 }