fix: show description for examples

Author: carowright

src/ApiResourceExampleDocument.d.ts

@@ -213,5 +213,7 @@ export class ApiResourceExampleDocument extends AmfHelperMixin(LitElement) {
 
   _computeExampleTitle(example: Example): string;
 
+  _computeExampleDescription(example: Example): string;
+
   _exampleTitleIsMediaType(example: Example): boolean;
 }

src/ApiResourceExampleDocument.js

@@ -561,6 +561,27 @@ export class ApiResourceExampleDocument extends AmfHelperMixin(LitElement) {
     return html`<div class="example-title">${label}</div>`;
   }
 
+  /**
+   * @param {Example} example
+   * @returns {string}
+   */
+  _computeExampleDescription(example) {
+    const { description } = example
+    return !description ? '' : description;
+  }
+
+  /**
+   * @param {Example} example
+   * @returns {TemplateResult|string}
+   */
+  _descriptionTemplate(example) {
+    if (example.isScalar) {
+      return '';
+    }
+    const description = this._computeExampleDescription(example)
+    return html`<div class="example-description">${description}</div>`;
+  }
+
   /**
    * Returns title to render for example
    * @param {Example} example 
@@ -596,6 +617,7 @@ export class ApiResourceExampleDocument extends AmfHelperMixin(LitElement) {
     return examples.map((item) => html`
     <div class="item-container">
       ${this._titleTemplate(item)}
+      ${this._descriptionTemplate(item)}
       <div class="renderer">
         <arc-icon class="info-icon" icon="code"></arc-icon>
         <api-example-render

src/styles/Document.js

@@ -46,4 +46,8 @@ api-example-render {
   overflow: auto;
   max-width: 100%;
 }
+  
+.example-description {
+  padding: 10px 12px;
+}
 `;

test/api-resource-example-document.test.js

@@ -562,6 +562,29 @@ describe('ApiResourceExampleDocument', () => {
     });
   });
 
+  describe('_computeExampleDescription()', () => {
+    let element = /** @type ApiResourceExampleDocument */ (null);
+
+    beforeEach(async () => {
+      element = await basicFixture();
+      await nextFrame();
+    });
+
+    it('returns empty if no description is present', () => {
+      const example = {};
+      const description = element._computeExampleDescription(example);
+      assert.equal(description, '');
+    });
+
+    it('returns description if present', () => {
+      const example = {
+        description: "example description",
+      };
+      const title = element._computeExampleDescription(example);
+      assert.equal(title, example.description);
+    });
+  });
+
   describe('a11y', () => {
     let element = /** @type ApiResourceExampleDocument */ (null);
     let amf;