Fix parameter description for OAS 3 (#20)

* fix: save description from shape, use if no description in property

* test: add test for shape description

* test: fix test

* 4.2.10

Author: twoplustwoone

demo/SE-17897/SE-17897.yaml

@@ -0,0 +1,21 @@
+openapi: '3.0.2'
+info:
+  title: 'SE-17897'
+  version: 1.0.0
+
+paths:
+  /default:
+    post:
+      parameters:
+        - in: query
+          name: conversationId
+          required: false
+          description: >
+            The ConversationId uniquely identifies the message sent from the sender to the receiver.
+          schema:
+            type: string
+            format: uuid
+          example: '242ab55c-de2b-4822-a411-945e85882b60'
+      responses:
+        '201':
+          description: Created

demo/apis.json

@@ -12,6 +12,7 @@
   "APIC-631/APIC-631.raml": "RAML 1.0",
   "SE-19500/SE-19500.raml": "RAML 1.0",
   "APIC-429/APIC-429.yaml": { "type": "OAS 3.0", "mime": "application/yaml" },
+  "SE-17897/SE-17897.yaml": { "type": "OAS 3.0", "mime": "application/yaml" },
   "new-oas3-types/new-oas3-types.yaml": { "type": "OAS 3.0", "mime": "application/yaml" },
   "oas-api/read-only-properties.yaml": { "type": "OAS 3.0", "mime": "application/yaml" }
 }

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-components/api-type-document",
   "description": "A documentation table for type (resource) properties. Works with AMF data model",
-  "version": "4.2.9",
+  "version": "4.2.10",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",

package.json

@@ -93,11 +93,21 @@ export class PropertyShapeDocument extends  PropertyDocumentMixin(LitElement) {
    * @attribute
    */
   propertyDescription: string;
+  /**
+   * A description of the shape to render.
+   * @attribute
+   */
+  shapeDescription: string;
   /**
    * Computed value, true if description is set.
    * @attribute
    */
   hasPropertyDescription: boolean;
+  /**
+   * Computed value, true if description is set.
+   * @attribute
+   */
+  hasShapeDescription: boolean;
   /**
    * A property to set when the component is rendered in the narrow
    * view. To be used with mobile rendering or when the

src/PropertyShapeDocument.d.ts

@@ -91,10 +91,18 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
        * A description of the property to render.
        */
       propertyDescription: { type: String },
+      /**
+       * A description of the shape to render.
+       */
+      shapeDescription: { type: String },      
       /**
        * Computed value, true if description is set.
        */
       hasPropertyDescription: { type: Boolean },
+      /**
+       * Computed value, true if description is set.
+       */
+      hasShapeDescription: { type: Boolean },
       /**
        * A property to set when the component is rendered in the narrow
        * view. To be used with mobile rendering or when the
@@ -223,6 +231,10 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
     }
     this.range = this._computeRange(shape);
     this.isRequired = this._computeIsRequired(shape);
+    this.shapeDescription = this._computeDescription(shape);
+    this.hasShapeDescription = this._computeHasStringValue(
+      this.shapeDescription
+    );
   }
 
   _rangeChanged(range) {
@@ -564,11 +576,11 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
    * @return {TemplateResult|string} Template for the description
    */
   _descriptionTemplate() {
-    if (!this.hasPropertyDescription) {
+    if (!(this.hasPropertyDescription || this.hasShapeDescription)) {
       return '';
     }
     return html`
-      <arc-marked .markdown="${this.propertyDescription}" sanitize>
+      <arc-marked .markdown="${this.propertyDescription || this.shapeDescription}" sanitize>
         <div slot="markdown-html" class="markdown-body"></div>
       </arc-marked>
     `;

src/PropertyShapeDocument.js

@@ -646,6 +646,36 @@ describe('PropertyShapeDocument', () => {
     });
   });
 
+  describe('SE-17897', () => {
+    [
+      ['Regular model', false],
+      ['Compact model', true],
+    ].forEach((item) => {
+      describe(String(item[0]), () => {
+        let element = /** @type PropertyShapeDocument */ (null);
+        let amf;
+
+        before(async () => {
+          amf = await AmfLoader.load(item[1], 'SE-17897')
+        });
+
+        beforeEach(async () => {
+          element = await basicFixture();
+          element.amf = amf;
+        });
+
+        it('sets shape description when schema does not have one', async () => {
+          const [parameter] = AmfLoader.lookupParameters(amf, '/default', 'post');
+          element.shape = parameter;
+          await nextFrame();
+          assert.isFalse(element.hasPropertyDescription);
+          assert.isTrue(element.hasShapeDescription);
+          assert.isTrue(element.shapeDescription.startsWith('The ConversationId uniquely identifies the message sent from the sender to the receiver.'));
+        });
+      });
+    });
+  });
+
   // this API does not produce amf_inline_type anymore
   // nor any inn the demos
   describe.skip('APIC-282', () => {