fix(schema-model): preserve descriptions on referenced properties and arrays [TDX-5454]

[arashsheyda]

Summary

ticket: https://konghq.atlassian.net/browse/TDX-5454

In the spec display when we have a property that is a user defined class or an array of classes, the definition in the main class is not displayed. In the example attached, I want to add more detail to the collection of stops but I can only update the single stop description.

[kongponents-bot]

Install the preview package from this PR

@kong/spec-renderer@pr-997

[kongponents-bot]

🔴 PR audit failed. 🔴

🔥 PNPM Audit issues detected.

┌─────────────────────┬────────────────────────────────────────────────────────┐
│ high                │ js-yaml: maxTotalMergeKeys does not limit CPU use for  │
│                     │ empty merge sources                                    │
├─────────────────────┼────────────────────────────────────────────────────────┤
│ Package             │ js-yaml                                                │
├─────────────────────┼────────────────────────────────────────────────────────┤
│ Vulnerable versions │ >=4.0.0 <4.3.2                                         │
├─────────────────────┼────────────────────────────────────────────────────────┤
│ Patched versions    │ >=4.3.2                                                │
├─────────────────────┼────────────────────────────────────────────────────────┤
│ Paths               │ .>@asyncapi/avro-schema-parser>@asyncapi/parser>js-    │
│                     │ yaml                                                   │
│                     │                                                        │
│                     │ .>@asyncapi/openapi-schema-parser>@asyncapi/parser>js- │
│                     │ yaml                                                   │
│                     │                                                        │
│                     │ .>@asyncapi/parser>js-yaml                             │
├─────────────────────┼────────────────────────────────────────────────────────┤
│ More info           │ https://github.com/advisories/GHSA-2883-xcg3-v3hh      │
└─────────────────────┴────────────────────────────────────────────────────────┘
1 vulnerabilities found
Severity: 1 high

PR with those issues cannot be merged.

How to resolve:

• Check open renovate PRs for updates to the dependencies mentioned in the audit report
• try to update dependencies listed in the audit report to the latest versions
• use pnpm audit --fix to automatically fix issues

[vaibhavrajsingh2001]

We need a better approach for handling descriptions being defined for array type schemas.
This PR adds a preference for picking up the schema's own description over the array item's description, but this means the array item's description isn't visible anywhere anymore.

[vaibhavrajsingh2001]

looks like we have multiple cases of fields being defined at the top level for array schemas, instead of being defined inside items.
So we should probably build a list of keys that need to be picked up from candidate itself instead of candidate.items