From 5b81fc6e542d8f37f0723d044ea0488bfc13350f Mon Sep 17 00:00:00 2001
From: Warren Parad <gpg@warrenparad.net>
Date: Wed, 15 May 2024 12:17:47 +0200
Subject: [PATCH] Prefer the array description to display when available over
 the items schema description. Fix #250.

---
 CHANGELOG.md              | 1 +
 src/utils/schema-utils.js | 9 ++++-----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef9b1309..93a1f4f6 100644
--- a/CHANGELOG.md
+++ b/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.
diff --git a/src/utils/schema-utils.js b/src/utils/schema-utils.js
index f3785bcc..b61be232 100644
--- a/src/utils/schema-utils.js
+++ b/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,7 +491,7 @@ 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&lt;${arrayItemsSchema.description}&gt;` : '');
+    obj['::description'] = schema.description || arrayItemsSchema?.description || '';
     obj['::flags'] = { '🆁': schema.readOnly && '🆁', '🆆': schema.writeOnly && '🆆' };
     obj['::link'] = arrayItemsSchema?.title || schema.title || '';
     obj['::type'] = 'array';
@@ -500,7 +499,7 @@ export function schemaInObjectNotation(rawSchema, options, level = 0, suffix = '
     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;
     }