Merge pull request #17 from advanced-rest-client/fix/example-description-missing

Fix/example description missing

Author: carowright

demo/APIC-332/APIC-332.raml

@@ -0,0 +1,22 @@
+#%RAML 1.0
+title: API with Examples
+
+types:
+  Org:
+    type: object
+    description: This description for the type is shown
+    properties:
+      name: string
+      address?: string
+      value?: string
+
+/organization:
+  post:
+    body:
+      application/json:
+        type: Org
+        example:
+          value:
+            name: Fake SA
+            value: Something
+          description: This description for the example is never shown

demo/apis.json

@@ -2,6 +2,7 @@
   "demo-api/demo-api.raml": "RAML 1.0",
   "raml-types/raml-types.raml": "RAML 1.0",
   "google-drive-api/google-drive-api.raml": "RAML 1.0",
+  "APIC-332/APIC-332.raml": "RAML 1.0",
   "oas-3-api/oas-3-api.yaml": { "type": "OAS 3.0", "mime": "application/yaml" },
   "steveTest-1/stevetest.json": { "type": "OAS 2.0", "mime": "application/json" }
 }

demo/index.js

@@ -110,6 +110,7 @@ class ApiDemo extends ApiDemoPage {
       ['demo-api', 'Demo API'],
       ['google-drive-api', 'Google Drive'],
       ['raml-types', 'RAML types with raml examples'],
+      ['APIC-332', 'APIC-332'],
     ].forEach(([file, label]) => {
       result[result.length] = html`
       <anypoint-item data-src="${file}-compact.json">${label} - compact model</anypoint-item>

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-components/api-resource-example-document",
   "description": "A viewer for examples in a resource based on AMF model",
-  "version": "4.3.2",
+  "version": "4.3.3",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",
@@ -35,7 +35,7 @@
     "@advanced-rest-client/prism-highlight": "^4.0.4",
     "@anypoint-web-components/anypoint-button": "^1.2.0",
     "@api-components/amf-helper-mixin": "^4.3.6",
-    "@api-components/api-example-generator": "^4.4.8",
+    "@api-components/api-example-generator": "^4.4.13",
     "lit-element": "^2.4.0"
   },
   "devDependencies": {

package.json

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

src/ApiResourceExampleDocument.d.ts

@@ -561,6 +561,30 @@ 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)
+    if (!description) {
+      return '';
+    }
+    return html`<div class="example-description">${description}</div>`;
+  }
+
   /**
    * Returns title to render for example
    * @param {Example} example 
@@ -596,6 +620,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/ApiResourceExampleDocument.js

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

src/styles/Document.js

@@ -32,7 +32,6 @@ describe('ApiResourceExampleDocument', () => {
     return localStorage.jsonTableEnabled;
   }
 
-
   describe('_tableChanged()', () => {
     let element = /** @type ApiResourceExampleDocument */ (null);
     beforeEach(async () => {
@@ -312,6 +311,23 @@ describe('ApiResourceExampleDocument', () => {
     return element._ensureArray(schema[key]);
   }
 
+  async function resolveWhenReady(elm, model, path, method, payloadIndex) {
+    return new Promise((resolve) => {
+      let payload = getPayload(elm, model, path, method);
+      if (payloadIndex !== undefined) {
+        payload = payload[payloadIndex]
+      }
+      elm.examples = payload;
+      elm.addEventListener('has-examples-changed', function f(e) {
+        if (!e.detail.value) {
+          return;
+        }
+        elm.removeEventListener('has-examples-changed', f);
+        setTimeout(() => resolve());
+      });
+    });
+  }
+
   describe('__computeExamples()', () => {
     [
       ['Regular model', false],
@@ -529,6 +545,34 @@ describe('ApiResourceExampleDocument', () => {
     });
   });
 
+  describe('APIC-332', () => {
+    [
+      ['Regular model', false],
+      ['Compact model', true]
+    ].forEach((item) => {
+      describe(String(item[0]), () => {
+        let amf;
+        before(async () => {
+          amf = await AmfLoader.load(item[1], 'APIC-332');
+        });
+
+        let element = /** @type ApiResourceExampleDocument */ (null);
+        beforeEach(async () => {
+          element = await basicFixture();
+          element.amf = amf;
+          await nextFrame();
+        });
+
+        it('renders description for an example', async () => {
+          element.mediaType = 'application/json';
+          await resolveWhenReady(element, amf, '/organization', 'post', 0);
+          const description = /** @type HTMLElement */ (element.shadowRoot.querySelector('.example-description'));
+          assert.equal(description.innerText, 'This description for the example is never shown');
+        });
+      });
+    });
+  });
+
   describe('_computeExampleTitle()', () => {
     let element = /** @type ApiResourceExampleDocument */ (null);
 
@@ -562,6 +606,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;
@@ -574,20 +641,6 @@ describe('ApiResourceExampleDocument', () => {
       element.amf = amf;
     });
 
-    async function resolveWhenReady(elm, model, path, method) {
-      return new Promise((resolve) => {
-        const payloads = getPayload(elm, model, path, method);
-        elm.examples = payloads;
-        elm.addEventListener('has-examples-changed', function f(e) {
-          if (!e.detail.value) {
-            return;
-          }
-          elm.removeEventListener('has-examples-changed', f);
-          setTimeout(() => resolve());
-        });
-      });
-    }
-
     it('passes accessibility test', async () => {
       await resolveWhenReady(element, amf, '/IncludedInType', 'post');
       await assert.isAccessible(element, {