fix (walker): show description for $ref in fragments of type array

src/__tests__/tree.spec.ts

@@ -757,6 +757,101 @@ describe('SchemaTree', () => {
         }),
       );
     });
+
+    it('node of type array should adopt description of referenced node', () => {
+      const schema = {
+        definitions: {
+          Cave: {
+            type: 'string',
+            summary: 'A cave',
+            description: '_Everyone_ ~hates~ loves caves',
+          },
+        },
+        type: 'object',
+        properties: {
+          caves: {
+            type: 'array',
+            items: {
+              $ref: '#/definitions/Cave',
+            },
+          },
+        },
+      };
+
+      const tree = new SchemaTree(schema);
+      tree.populate();
+
+      expect(
+        // @ts-ignore
+        tree.root.children[0].children[0].annotations.description,
+      ).toEqual('_Everyone_ ~hates~ loves caves');
+    });
+
+    it('node of type array should keep its own description even when referenced node has a description', () => {
+      const schema = {
+        definitions: {
+          Cave: {
+            type: 'string',
+            summary: 'A cave',
+            description: '_Everyone_ ~hates~ loves caves',
+          },
+        },
+        type: 'object',
+        properties: {
+          caves: {
+            type: 'array',
+            description: 'I have my own description',
+            items: {
+              $ref: '#/definitions/Cave',
+            },
+          },
+        },
+      };
+
+      const tree = new SchemaTree(schema);
+      tree.populate();
+
+      expect(
+        // @ts-ignore
+        tree.root.children[0].children[0].annotations.description,
+      ).toEqual('I have my own description');
+    });
+
+    it('referenced node description should appear for all properties with that ref', () => {
+      const schema = {
+        definitions: {
+          Cave: {
+            type: 'string',
+            summary: 'A cave',
+            description: '_Everyone_ ~hates~ loves caves',
+          },
+        },
+        type: 'object',
+        properties: {
+          caves: {
+            type: 'array',
+            items: {
+              $ref: '#/definitions/Cave',
+            },
+          },
+          bear: {
+            $ref: '#/definitions/Cave',
+          },
+        },
+      };
+
+      const tree = new SchemaTree(schema);
+      tree.populate();
+
+      expect(
+        // @ts-ignore
+        tree.root.children[0].children[0].annotations.description,
+      ).toEqual('_Everyone_ ~hates~ loves caves');
+      expect(
+        // @ts-ignore
+        tree.root.children[0].children[1].annotations.description,
+      ).toEqual('_Everyone_ ~hates~ loves caves');
+    });
   });
 
   describe('position', () => {

src/walker/walker.ts

@@ -295,7 +295,29 @@ export class Walker extends EventEmitter<WalkerEmitter> {
         return [new ReferenceNode(fragment, null), fragment];
       }
     }
-
+    //fragment with type 'array' and no description should adopt description of $ref if it exists
+    if (fragment.type === 'array' && fragment.description === void 0) {
+      if (fragment.items !== void 0 && isObjectLiteral(fragment.items)) {
+        for (const key of Object.keys(fragment.items)) {
+          if (key === '$ref') {
+            const refToResolve = fragment.items[key];
+            if (typeof refToResolve !== 'string') {
+              return [new ReferenceNode(fragment, '$ref is not a string'), fragment];
+            } else if (walkingOptions.resolveRef !== null) {
+              try {
+                let newFragment = walkingOptions.resolveRef(path, refToResolve);
+                if (newFragment.description !== void 0) {
+                  newFragment = { ...newFragment };
+                  Object.assign(fragment, { description: newFragment.description });
+                }
+              } catch (ex) {
+                super.emit('error', createMagicError(ex));
+              }
+            }
+          }
+        }
+      }
+    }
     let initialFragment: ProcessedFragment = fragment;
     if (walkingOptions.mergeAllOf && SchemaCombinerName.AllOf in fragment) {
       try {