Add support for deprecated properties (#23)

* feat: styling changes for deprecated properties, show warning label if deprecated

* chore: change deprecated message

* chore: add documentation, remove console.log

* test: added tests for deprecated properties

* chore(demo): add model

* chore(demo): add new API to demo list, move Demo API to top

* 4.2.11

* 4.2.12

* chore: update amf-helper-mixin

* fix: changed warninig message style

Author: twoplustwoone

demo/APIC-649/APIC-649.yaml

@@ -0,0 +1,118 @@
+openapi: "3.0.0"
+
+info:
+  description: This is a simple API
+  version: "1.0.0"
+  title: Simple Inventory API
+  contact:
+    email: [email protected]
+  license:
+    name: Apache 2.0
+    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+tags:
+  - name: admins
+    description: Secured Admin-only calls
+  - name: developers
+    description: Operations available to regular developers
+paths:
+  /inventory:
+    get:
+      tags:
+        - developers
+      summary: searches inventory
+      operationId: searchInventory
+      description: |
+        By passing in the appropriate options, you can search for
+        available inventory in the system
+      parameters:
+        - in: query
+          name: searchString
+          description: pass an optional search string for looking up inventory
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: skip
+          description: number of records to skip for pagination
+          schema:
+            type: integer
+            format: int32
+            minimum: 0
+        - in: query
+          name: limit
+          description: maximum number of records to return
+          schema:
+            type: integer
+            format: int32
+            minimum: 0
+            maximum: 50
+      responses:
+        '200':
+          description: search results matching criteria
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/InventoryItem'
+        '400':
+          description: bad input parameter
+    post:
+      tags:
+        - admins
+      summary: adds an inventory item
+      operationId: addInventory
+      description: Adds an item to the system
+      responses:
+        '201':
+          description: item created
+        '400':
+          description: 'invalid input, object invalid'
+        '409':
+          description: an existing item already exists
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InventoryItem'
+        description: Inventory item to add
+components:
+  schemas:
+    InventoryItem:
+      type: object
+      required:
+        - id
+        - name
+        - manufacturer
+        - releaseDate
+      properties:
+        id:
+          type: string
+          format: uuid
+          example: d290f1ee-6c54-4b01-90e6-d701748f0851
+        name:
+          type: string
+          example: Widget Adapter
+        releaseDate:
+          type: string
+          format: date-time
+          example: '2016-08-29T09:12:33.001Z'
+        manufacturer:
+          $ref: '#/components/schemas/Manufacturer'
+    Manufacturer:
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          example: ACME Corporation
+          deprecated: true
+        homePage:
+          type: string
+          format: url
+          example: 'https://www.acme-corp.com'
+        phone:
+          type: string
+          example: 408-867-5309
+          deprecated: true
+      type: object

demo/apis.json

@@ -15,5 +15,6 @@
   "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" }
+  "oas-api/read-only-properties.yaml": { "type": "OAS 3.0", "mime": "application/yaml" },
+  "APIC-649/APIC-649.yaml": { "type": "OAS 3.0", "mime": "application/yaml" }
 }

demo/index.js

@@ -99,8 +99,9 @@ class ApiDemo extends ApiDemoPage {
 
   _apiListTemplate() {
     return [
-      ['APIC-429', 'APIC 429'],
       ['demo-api', 'Demo API'],
+      ['APIC-649', 'Deprecated properties'],
+      ['APIC-429', 'APIC 429'],
       ['read-only-properties', 'Read Only Properties API'],
       ['examples-api', 'Examples render demo'],
       ['Petstore', 'OAS: Petstore'],

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.11",
+  "version": "4.2.12",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",

package.json

@@ -133,6 +133,11 @@ export class PropertyShapeDocument extends  PropertyDocumentMixin(LitElement) {
    * @attribute
    */
   renderReadOnly: boolean;
+  /**
+   * Determines if shape's range is deprecated
+   * @attribute
+   */
+  deprecated: boolean
 
   get complexToggleLabel(): string;
 

src/PropertyShapeDocument.d.ts

@@ -126,6 +126,10 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
        * Computed value from the shape. True if the property is an anyOf
        */
       isAnyOf: { type: Boolean },
+      /**
+       * Determines if shape's range is deprecated
+       */
+      deprecated: { type: Boolean, reflect: true },
     };
   }
 
@@ -208,6 +212,7 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
     this.hasPropertyDescription = false;
     this.narrow = false;
     this.renderReadOnly = false;
+    this.deprecated = false;
   }
 
   connectedCallback() {
@@ -268,6 +273,12 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
       this.propertyName
     );
     this.propertyDataType = this._computeObjectDataType(range, shape);
+    const isDeprecated = Boolean(this._computeIsDeprecated(range));
+    this.deprecated = isDeprecated;
+  }
+
+  _computeIsDeprecated(range) {
+    return this._getValue(range, this._getAmfKey(this.ns.aml.vocabularies.shapes.deprecated))
   }
 
   _computeObjectDataType(range, shape) {
@@ -633,6 +644,13 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
       : ''}`;
   }
 
+  _deprecatedWarningTemplate() {
+    if (!this.deprecated) {
+      return '';
+    }
+    return html`<div class="deprecated-warning">Warning: Deprecated</div>`
+  }
+
   /**
    * @return {TemplateResult} Main render function.
    */
@@ -665,6 +683,7 @@ export class PropertyShapeDocument extends PropertyDocumentMixin(LitElement) {
             >`
           : ''}
       </div>
+      ${this._deprecatedWarningTemplate()}
       ${this._descriptionTemplate()}
       <property-range-document
         .amf="${this.amf}"

src/PropertyShapeDocument.js

@@ -164,4 +164,22 @@ export default css`
     background-color: var(--api-type-readonly-property-background-color, #ff9292);
     color: var(--api-type-readonly-property-color, black);
   }
+
+  :host([deprecated]) .property-title {
+    color: gray;
+    text-decoration: line-through;
+  }
+
+  :host([deprecated]) .property-traits > span {
+    background-color: var(--api-type-document-type-deprecated-background-color, gray);
+    color: var(--api-type-document-type-deprecated-color, white);
+  }
+
+  .deprecated-warning {
+    background-color: var(--api-type-document-type-deprecated-background-color, gray);
+    color: var(--api-type-document-type-deprecated-color, white);
+    padding: var(--api-type-document-deprecated-warning-padding, 3px 6px);
+    border-radius: var(--api-type-document-deprecated-warning-border-radius, 3px);
+    display: inline-flex;
+  }
 `;

src/ShapeStyles.js

@@ -676,6 +676,34 @@ describe('PropertyShapeDocument', () => {
     });
   });
 
+  describe('Deprecated properties', () => {
+    [
+      ['Regular model', false],
+      ['Compact model', true],
+    ].forEach(([label, compact]) => {
+      describe(String(label), () => {
+        let amf;
+        let type;
+
+        before(async () => {
+          [amf, type] = await AmfLoader.loadType('Manufacturer', compact, 'APIC-649');
+        });
+
+        it('should set `deprecated` property', async () => {
+          const shape = AmfLoader.lookupPropertyShape(amf, type, 'name');
+          const element = await modelFixture(amf, shape);
+          assert.isTrue(element.deprecated);
+        });
+
+        it('should set render deprecated warning message', async () => {
+          const shape = AmfLoader.lookupPropertyShape(amf, type, 'name');
+          const element = await modelFixture(amf, shape);
+          assert.exists(element.shadowRoot.querySelector('.deprecated-warning'));
+        });
+      });
+    });
+  });
+
   // this API does not produce amf_inline_type anymore
   // nor any inn the demos
   describe.skip('APIC-282', () => {