Merge pull request #251 from Authress-Engineering/fix-item-descriptions

Prefer the array description to display when available over the items schema description. Fix #250.

CHANGELOG.md

@@ -10,6 +10,7 @@ This package follows standard semvar, `<major>.<minor>.<build>`. No breaking cha
 * Remove deprecated property `nav-item-spacing` in favor of css variable `--nav-path-padding`.
 * Prevent making requests when required path parameters are not specified.
 * Automatically retry fetching the spec if it doesn't work for any reason.
+* Fix array description display preference to be first--The Array description, and then only second--The array item schema description, so that the "more specific" description wins, even though the "items" description is more deeply nested. This aligns to the expected behavior of preference in the json schema.
 
 ## 2.1
 * Add `x-locale` vendor extension to specify the locale of the spec.

src/utils/schema-utils.js

@@ -446,13 +446,12 @@ export function schemaInObjectNotation(rawSchema, options, level = 0, suffix = '
         } else if (v === 'array') {
           multiTypeOptions[`::OPTION~${i + 1}`] = {
             '::title': schema.title || '',
-            '::description': schema.description || '',
+            '::description': schema.description || arrayItemsSchema?.description || '',
             '::flags': { '🆁': schema.readOnly && '🆁', '🆆': schema.writeOnly && '🆆' },
             '::link': arrayItemsSchema.title || schema.title || '',
             '::type': 'array',
             // Array properties are read from the ::props object instead of reading from the keys of this object
-            // '::props': schemaInObjectNotation(Object.assign({ deprecated: schema.deprecated, readOnly: schema.readOnly, writeOnly: schema.writeOnly }, arrayItemsSchema), options, (level + 1)),
-            '::props': schemaInObjectNotation(Object.assign({}, schema, arrayItemsSchema), options, (level + 1)),
+            '::props': schemaInObjectNotation(Object.assign({}, schema, arrayItemsSchema, { description: schema.description || arrayItemsSchema?.description }), options, (level + 1)),
             '::deprecated': schema.deprecated || false,
             '::metadata': metadata
           };
@@ -492,15 +491,15 @@ export function schemaInObjectNotation(rawSchema, options, level = 0, suffix = '
   if (propertyType === 'array' || arrayItemsSchema) { // If Array
     const obj = { '::type': '' };
     obj['::title'] = schema.title || '';
-    obj['::description'] = schema.description || (arrayItemsSchema?.description ? `array<${arrayItemsSchema.description}>` : '');
+    obj['::description'] = schema.description || arrayItemsSchema?.description || '';
     obj['::flags'] = { '🆁': schema.readOnly && '🆁', '🆆': schema.writeOnly && '🆆' };
     obj['::link'] = arrayItemsSchema?.title || schema.title || '';
     obj['::type'] = 'array';
     obj['::deprecated'] = schema.deprecated || false;
     obj['::metadata'] = metadata;
     // Array properties are read from the ::props object instead of reading from the keys of this object
     // Use type: undefined to prevent schema recursion by passing array from the parent to the next loop. arrayItemsSchema should have had type defined but it doesn't.
-    obj['::props'] = schemaInObjectNotation(Object.assign({}, schema, { type: undefined }, arrayItemsSchema), options, (level + 1));
+    obj['::props'] = schemaInObjectNotation(Object.assign({}, schema, { type: undefined }, arrayItemsSchema, { description: obj['::description'] }), options, (level + 1));
     if (arrayItemsSchema?.items) {
       obj['::array-type'] = arrayItemsSchema.items.type;
     }