Merge pull request #1766 from Redocly/fix/missing-description-when-ref-used-1727

fix: OpenAPI 3.1: Missing description when $ref used #1727

src/services/OpenAPIParser.ts

@@ -174,6 +174,18 @@ export class OpenAPIParser {
     return obj;
   }
 
+  shallowDeref<T extends unknown>(obj: OpenAPIRef | T): T {
+    if (this.isRef(obj)) {
+      const schemaName = getDefinitionName(obj.$ref);
+      if (schemaName && this.options.ignoreNamedSchemas.has(schemaName)) {
+        return { type: 'object', title: schemaName } as T;
+      }
+      const resolved = this.byRef<T>(obj.$ref);
+      return this.allowMergeRefs ? this.mergeRefs(obj, resolved, false) : (resolved as T);
+    }
+    return obj;
+  }
+
   mergeRefs(ref, resolved, mergeAsAllOf: boolean) {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { $ref, ...rest } = ref;
@@ -194,13 +206,6 @@ export class OpenAPIParser {
     }
   }
 
-  shalowDeref<T extends object>(obj: OpenAPIRef | T): T {
-    if (this.isRef(obj)) {
-      return this.byRef<T>(obj.$ref)!;
-    }
-    return obj;
-  }
-
   /**
    * Merge allOf constraints.
    * @param schema schema with allOF

src/services/__tests__/OpenAPIParser.test.ts

@@ -1,5 +1,6 @@
 import { OpenAPIParser } from '../OpenAPIParser';
 import { RedocNormalizedOptions } from '../RedocNormalizedOptions';
+import { OpenAPIParameter, Referenced } from '../../types';
 
 const opts = new RedocNormalizedOptions({});
 
@@ -13,5 +14,18 @@ describe('Models', () => {
       parser = new OpenAPIParser(spec, undefined, opts);
       expect(parser.mergeAllOf(spec.components.schemas.test)).toMatchSnapshot();
     });
+
+    test('should override description from $ref of the referenced component, when sibling description exists ', () => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const spec = require('./fixtures/siblingRefDescription.json');
+      parser = new OpenAPIParser(spec, undefined, opts);
+      const schemaOrRef: Referenced<OpenAPIParameter> = {
+        $ref: '#/components/schemas/Test',
+        description: 'Overriden description',
+      };
+
+      expect(parser.shallowDeref(schemaOrRef)).toMatchSnapshot();
+    });
+
   });
 });

src/services/__tests__/__snapshots__/OpenAPIParser.test.ts.snap

@@ -86,3 +86,10 @@ Object {
   ],
 }
 `;
+
+exports[`Models Schema should override description from $ref of the referenced component, when sibling description exists  1`] = `
+Object {
+  "description": "Overriden description",
+  "type": "object",
+}
+`;

src/services/__tests__/fixtures/siblingRefDescription.json

@@ -0,0 +1,39 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "AA",
+    "version": "1.0"
+  },
+  "paths": {
+    "/test": {
+      "get": {
+        "operationId": "test",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "testAttr": {
+                      "description": "Overriden description",
+                      "$ref": "#/components/schemas/Test"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Test": {
+        "type": "object",
+        "description": "Refed description"
+      }
+    }
+  }
+}

src/services/models/MediaType.ts

@@ -40,7 +40,7 @@ export class MediaTypeModel {
       this.examples = {
         default: new ExampleModel(
           parser,
-          { value: parser.shalowDeref(info.example) },
+          { value: parser.shallowDeref(info.example) },
           name,
           info.encoding,
         ),

src/services/models/Schema.ts

@@ -78,7 +78,7 @@ export class SchemaModel {
     makeObservable(this);
 
     this.pointer = schemaOrRef.$ref || pointer || '';
-    this.rawSchema = parser.deref(schemaOrRef, false, true);
+    this.rawSchema = parser.shallowDeref(schemaOrRef);
     this.schema = parser.mergeAllOf(this.rawSchema, this.pointer, isChild);
 
     this.init(parser, isChild);

src/utils/openapi.ts

@@ -505,13 +505,13 @@ export function mergeParams(
 ): Array<Referenced<OpenAPIParameter>> {
   const operationParamNames = {};
   operationParams.forEach(param => {
-    param = parser.shalowDeref(param);
+    param = parser.shallowDeref(param);
     operationParamNames[param.name + '_' + param.in] = true;
   });
 
   // filter out path params overridden by operation ones with the same name
   pathParams = pathParams.filter(param => {
-    param = parser.shalowDeref(param);
+    param = parser.shallowDeref(param);
     return !operationParamNames[param.name + '_' + param.in];
   });