feat(ns-openapi-2): add support for Example Object (#3247)

Refs #3097
swagger-api · Oct 10, 2023 · e9d1e3e · e9d1e3e
1 parent 7adf623
commit e9d1e3e
Show file tree

Hide file tree

Showing 12 changed files with 231 additions and 68 deletions.
diff --git a/packages/apidom-ns-openapi-2/README.md b/packages/apidom-ns-openapi-2/README.md
@@ -197,7 +197,7 @@ Only fully implemented specification objects should be checked here.
 - [ ] [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-responses-object)
 - [ ] [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-response-object)
 - [ ] [Headers Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-headers-object)
-- [ ] [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-example-object)
+- [x] [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-example-object)
 - [ ] [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-header-object)
 - [x] [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-tag-object)
 - [ ] [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-reference-object)

diff --git a/packages/apidom-ns-openapi-2/src/elements/Example.ts b/packages/apidom-ns-openapi-2/src/elements/Example.ts
@@ -0,0 +1,10 @@
+import { ObjectElement, Attributes, Meta } from '@swagger-api/apidom-core';
+
+class Example extends ObjectElement {
+  constructor(content?: Record<string, unknown>, meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = 'example';
+  }
+}
+
+export default Example;
diff --git a/packages/apidom-ns-openapi-2/src/index.ts b/packages/apidom-ns-openapi-2/src/index.ts
@@ -24,6 +24,7 @@ export {
   isLicenseElement,
   isContactElement,
   isExternalDocumentationElement,
+  isExampleElement,
   isTagElement,
   isXmlElement,
   isSecurityDefinitionsElement,
@@ -40,6 +41,7 @@ export {
   LicenseElement,
   ContactElement,
   ExternalDocumentationElement,
+  ExampleElement,
   TagElement,
   XmlElement,
   SecurityDefinitionsElement,

diff --git a/packages/apidom-ns-openapi-2/src/namespace.ts b/packages/apidom-ns-openapi-2/src/namespace.ts
@@ -4,6 +4,7 @@ import InfoElement from './elements/Info';
 import LicenseElement from './elements/License';
 import ContactElement from './elements/Contact';
 import ExternalDocumentation from './elements/ExternalDocumentation';
+import ExampleElement from './elements/Example';
 import TagElement from './elements/Tag';
 import XmlElement from './elements/Xml';
 import SecurityDefinitionsElement from './elements/SecurityDefinitions';
@@ -19,6 +20,7 @@ const openApi2 = {
     base.register('license', LicenseElement);
     base.register('contact', ContactElement);
     base.register('externalDocumentation', ExternalDocumentation);
+    base.register('example', ExampleElement);
     base.register('tag', TagElement);
     base.register('xml', XmlElement);
     base.register('securityDefinitions', SecurityDefinitionsElement);

diff --git a/packages/apidom-ns-openapi-2/src/predicates.ts b/packages/apidom-ns-openapi-2/src/predicates.ts
@@ -4,23 +4,14 @@ import InfoElement from './elements/Info';
 import LicenseElement from './elements/License';
 import ContactElement from './elements/Contact';
 import ExternalDocumentation from './elements/ExternalDocumentation';
+import ExampleElement from './elements/Example';
 import TagElement from './elements/Tag';
 import XmlElement from './elements/Xml';
 import SecurityDefinitionsElement from './elements/SecurityDefinitions';
 import SecuritySchemeElement from './elements/SecurityScheme';
 import SecurityRequirementElement from './elements/SecurityRequirement';
 import ScopesElement from './elements/Scopes';
 
-export const isTagElement = createPredicate(
-  ({ hasBasicElementProps, isElementType, primitiveEq }) => {
-    return (element: any) =>
-      element instanceof TagElement ||
-      (hasBasicElementProps(element) &&
-        isElementType('tag', element) &&
-        primitiveEq('object', element));
-  },
-);
-
 export const isInfoElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     return (element: any) =>
@@ -60,6 +51,26 @@ export const isExternalDocumentationElement = createPredicate(
   },
 );
 
+export const isExampleElement = createPredicate(
+  ({ hasBasicElementProps, isElementType, primitiveEq }) => {
+    return (element: any) =>
+      element instanceof ExampleElement ||
+      (hasBasicElementProps(element) &&
+        isElementType('example', element) &&
+        primitiveEq('object', element));
+  },
+);
+
+export const isTagElement = createPredicate(
+  ({ hasBasicElementProps, isElementType, primitiveEq }) => {
+    return (element: any) =>
+      element instanceof TagElement ||
+      (hasBasicElementProps(element) &&
+        isElementType('tag', element) &&
+        primitiveEq('object', element));
+  },
+);
+
 export const isXmlElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     return (element: any) =>

diff --git a/packages/apidom-ns-openapi-2/src/refractor/registration.ts b/packages/apidom-ns-openapi-2/src/refractor/registration.ts
@@ -2,6 +2,7 @@ import InfoElement from '../elements/Info';
 import LicenseElement from '../elements/License';
 import ContactElement from '../elements/Contact';
 import ExternalDocumentationElement from '../elements/ExternalDocumentation';
+import ExampleElement from '../elements/Example';
 import TagElement from '../elements/Tag';
 import XmlElement from '../elements/Xml';
 import SecurityDefinitionsElement from '../elements/SecurityDefinitions';
@@ -33,6 +34,13 @@ ExternalDocumentationElement.refract = createRefractor([
   'ExternalDocumentation',
   '$visitor',
 ]);
+ExampleElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Example',
+  '$visitor',
+]);
 TagElement.refract = createRefractor(['visitors', 'document', 'objects', 'Tag', '$visitor']);
 XmlElement.refract = createRefractor(['visitors', 'document', 'objects', 'XML', '$visitor']);
 SecurityDefinitionsElement.refract = createRefractor([
@@ -63,6 +71,7 @@ export {
   LicenseElement,
   ContactElement,
   ExternalDocumentationElement,
+  ExampleElement,
   TagElement,
   XmlElement,
   SecurityDefinitionsElement,

diff --git a/packages/apidom-ns-openapi-2/src/refractor/specification.ts b/packages/apidom-ns-openapi-2/src/refractor/specification.ts
@@ -4,6 +4,7 @@ import InfoVersionVisitor from './visitors/open-api-2/info/VersionVisitor';
 import LicenseVisitor from './visitors/open-api-2/license';
 import ContactVisitor from './visitors/open-api-2/contact';
 import ExternalDocumentationElement from './visitors/open-api-2/external-documentation';
+import ExampleVisitor from './visitors/open-api-2/example';
 import TagVisitor from './visitors/open-api-2/tag';
 import XmlVisitor from './visitors/open-api-2/xml';
 import SecurityDefinitionsVisitor from './visitors/open-api-2/security-definitions';
@@ -63,6 +64,9 @@ const specification = {
             url: FallbackVisitor,
           },
         },
+        Example: {
+          $visitor: ExampleVisitor,
+        },
         Tag: {
           $visitor: TagVisitor,
           fixedFields: {

diff --git a/packages/apidom-ns-openapi-2/src/refractor/visitors/open-api-2/example/index.ts b/packages/apidom-ns-openapi-2/src/refractor/visitors/open-api-2/example/index.ts
@@ -0,0 +1,18 @@
+import stampit from 'stampit';
+import { always } from 'ramda';
+
+import ExampleElement from '../../../../elements/Example';
+import FallbackVisitor from '../../FallbackVisitor';
+import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+
+const ExampleVisitor = stampit(FixedFieldsVisitor, FallbackVisitor, {
+  props: {
+    specPath: always(['document', 'objects', 'Example']),
+    canSupportSpecificationExtensions: false,
+  },
+  init() {
+    this.element = new ExampleElement();
+  },
+});
+
+export default ExampleVisitor;
diff --git a/packages/apidom-ns-openapi-2/src/traversal/visitor.ts b/packages/apidom-ns-openapi-2/src/traversal/visitor.ts
@@ -23,6 +23,7 @@ export const keyMap = {
   LicenseElement: ['content'],
   ContactElement: ['content'],
   ExternalDocumentationElement: ['content'],
+  ExampleElement: ['content'],
   TagElement: ['content'],
   XmlElement: ['content'],
   SecurityDefinitionsElement: ['content'],

diff --git a/packages/apidom-ns-openapi-2/test/predicates.ts b/packages/apidom-ns-openapi-2/test/predicates.ts
@@ -5,6 +5,7 @@ import {
   LicenseElement,
   ContactElement,
   ExternalDocumentationElement,
+  ExampleElement,
   TagElement,
   XmlElement,
   SecurityDefinitionsElement,
@@ -15,6 +16,7 @@ import {
   isLicenseElement,
   isContactElement,
   isExternalDocumentationElement,
+  isExampleElement,
   isTagElement,
   isXmlElement,
   isSecurityDefinitionsElement,
@@ -24,63 +26,6 @@ import {
 } from '../src';
 
 describe('predicates', function () {
-  context('isTagElement', function () {
-    context('given TagElement instance value', function () {
-      specify('should return true', function () {
-        const element = new TagElement();
-
-        assert.isTrue(isTagElement(element));
-      });
-    });
-
-    context('given subtype instance value', function () {
-      specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
-        class TagSubElement extends TagElement {}
-
-        assert.isTrue(isTagElement(new TagSubElement()));
-      });
-    });
-
-    context('given non TagSubElement instance value', function () {
-      specify('should return false', function () {
-        assert.isFalse(isTagElement(1));
-        assert.isFalse(isTagElement(null));
-        assert.isFalse(isTagElement(undefined));
-        assert.isFalse(isTagElement({}));
-        assert.isFalse(isTagElement([]));
-        assert.isFalse(isTagElement('string'));
-      });
-    });
-
-    specify('should support duck-typing', function () {
-      const tagElementDuck = {
-        _storedElement: 'tag',
-        _content: [],
-        primitive() {
-          return 'object';
-        },
-        get element() {
-          return this._storedElement;
-        },
-      };
-
-      const tagElementSwan = {
-        _storedElement: undefined,
-        _content: undefined,
-        primitive() {
-          return 'swan';
-        },
-        get length() {
-          return 0;
-        },
-      };
-
-      assert.isTrue(isTagElement(tagElementDuck));
-      assert.isFalse(isTagElement(tagElementSwan));
-    });
-  });
-
   context('isInfoElement', function () {
     context('given InfoElement instance value', function () {
       specify('should return true', function () {
@@ -309,6 +254,120 @@ describe('predicates', function () {
     });
   });
 
+  context('isExampleElement', function () {
+    context('given ExampleElement instance value', function () {
+      specify('should return true', function () {
+        const element = new ExampleElement();
+
+        assert.isTrue(isExampleElement(element));
+      });
+    });
+
+    context('given subtype instance value', function () {
+      specify('should return true', function () {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        class ExampleSubElement extends ExampleElement {}
+
+        assert.isTrue(isExampleElement(new ExampleSubElement()));
+      });
+    });
+
+    context('given non ExampleSubElement instance value', function () {
+      specify('should return false', function () {
+        assert.isFalse(isExampleElement(1));
+        assert.isFalse(isExampleElement(null));
+        assert.isFalse(isExampleElement(undefined));
+        assert.isFalse(isExampleElement({}));
+        assert.isFalse(isExampleElement([]));
+        assert.isFalse(isExampleElement('string'));
+      });
+    });
+
+    specify('should support duck-typing', function () {
+      const exampleElementDuck = {
+        _storedElement: 'example',
+        _content: [],
+        primitive() {
+          return 'object';
+        },
+        get element() {
+          return this._storedElement;
+        },
+      };
+
+      const exampleElementSwan = {
+        _storedElement: undefined,
+        _content: undefined,
+        primitive() {
+          return 'swan';
+        },
+        get length() {
+          return 0;
+        },
+      };
+
+      assert.isTrue(isExampleElement(exampleElementDuck));
+      assert.isFalse(isExampleElement(exampleElementSwan));
+    });
+  });
+
+  context('isTagElement', function () {
+    context('given TagElement instance value', function () {
+      specify('should return true', function () {
+        const element = new TagElement();
+
+        assert.isTrue(isTagElement(element));
+      });
+    });
+
+    context('given subtype instance value', function () {
+      specify('should return true', function () {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        class TagSubElement extends TagElement {}
+
+        assert.isTrue(isTagElement(new TagSubElement()));
+      });
+    });
+
+    context('given non TagSubElement instance value', function () {
+      specify('should return false', function () {
+        assert.isFalse(isTagElement(1));
+        assert.isFalse(isTagElement(null));
+        assert.isFalse(isTagElement(undefined));
+        assert.isFalse(isTagElement({}));
+        assert.isFalse(isTagElement([]));
+        assert.isFalse(isTagElement('string'));
+      });
+    });
+
+    specify('should support duck-typing', function () {
+      const tagElementDuck = {
+        _storedElement: 'tag',
+        _content: [],
+        primitive() {
+          return 'object';
+        },
+        get element() {
+          return this._storedElement;
+        },
+      };
+
+      const tagElementSwan = {
+        _storedElement: undefined,
+        _content: undefined,
+        primitive() {
+          return 'swan';
+        },
+        get length() {
+          return 0;
+        },
+      };
+
+      assert.isTrue(isTagElement(tagElementDuck));
+      assert.isFalse(isTagElement(tagElementSwan));
+    });
+  });
+
   context('isXmlElement', function () {
     context('given XmlElement instance value', function () {
       specify('should return true', function () {