feat(ns-openapi-2): add support for Headers Object (#3256)

Refs #3097
swagger-api · Oct 12, 2023 · a756102 · a756102
1 parent 7c4f69e
commit a756102
Show file tree

Hide file tree

Showing 13 changed files with 149 additions and 17 deletions.
diff --git a/packages/apidom-ns-openapi-2/README.md b/packages/apidom-ns-openapi-2/README.md
@@ -196,7 +196,7 @@ Only fully implemented specification objects should be checked here.
 - [x] [Items Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-items-object)
 - [ ] [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)
+- [x] [Headers Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-headers-object)
 - [x] [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#user-content-example-object)
 - [x] [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)

diff --git a/packages/apidom-ns-openapi-2/src/elements/Headers.ts b/packages/apidom-ns-openapi-2/src/elements/Headers.ts
@@ -0,0 +1,10 @@
+import { ObjectElement, Attributes, Meta } from '@swagger-api/apidom-core';
+
+class Headers extends ObjectElement {
+  constructor(content?: Record<string, unknown>, meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = 'headers';
+  }
+}
+
+export default Headers;
diff --git a/packages/apidom-ns-openapi-2/src/index.ts b/packages/apidom-ns-openapi-2/src/index.ts
@@ -25,6 +25,7 @@ export {
   isContactElement,
   isExternalDocumentationElement,
   isItemsElement,
+  isHeadersElement,
   isExampleElement,
   isHeaderElement,
   isTagElement,
@@ -44,6 +45,7 @@ export {
   ContactElement,
   ExternalDocumentationElement,
   ItemsElement,
+  HeadersElement,
   ExampleElement,
   HeaderElement,
   TagElement,

diff --git a/packages/apidom-ns-openapi-2/src/namespace.ts b/packages/apidom-ns-openapi-2/src/namespace.ts
@@ -6,6 +6,7 @@ import ContactElement from './elements/Contact';
 import ExternalDocumentation from './elements/ExternalDocumentation';
 import ItemsElement from './elements/Items';
 import ExampleElement from './elements/Example';
+import HeadersElement from './elements/Headers';
 import HeaderElement from './elements/Header';
 import TagElement from './elements/Tag';
 import XmlElement from './elements/Xml';
@@ -23,6 +24,7 @@ const openApi2 = {
     base.register('contact', ContactElement);
     base.register('externalDocumentation', ExternalDocumentation);
     base.register('items', ItemsElement);
+    base.register('headers', HeadersElement);
     base.register('example', ExampleElement);
     base.register('header', HeaderElement);
     base.register('tag', TagElement);

diff --git a/packages/apidom-ns-openapi-2/src/predicates.ts b/packages/apidom-ns-openapi-2/src/predicates.ts
@@ -6,6 +6,7 @@ import ContactElement from './elements/Contact';
 import ExternalDocumentation from './elements/ExternalDocumentation';
 import ItemsElement from './elements/Items';
 import ExampleElement from './elements/Example';
+import HeadersElement from './elements/Headers';
 import HeaderElement from './elements/Header';
 import TagElement from './elements/Tag';
 import XmlElement from './elements/Xml';
@@ -63,6 +64,16 @@ export const isItemsElement = createPredicate(
   },
 );
 
+export const isHeadersElement = createPredicate(
+  ({ hasBasicElementProps, isElementType, primitiveEq }) => {
+    return (element: unknown) =>
+      element instanceof HeadersElement ||
+      (hasBasicElementProps(element) &&
+        isElementType('headers', element) &&
+        primitiveEq('object', element));
+  },
+);
+
 export const isExampleElement = createPredicate(
   ({ hasBasicElementProps, isElementType, primitiveEq }) => {
     return (element: unknown) =>

diff --git a/packages/apidom-ns-openapi-2/src/refractor/registration.ts b/packages/apidom-ns-openapi-2/src/refractor/registration.ts
@@ -3,6 +3,7 @@ import LicenseElement from '../elements/License';
 import ContactElement from '../elements/Contact';
 import ExternalDocumentationElement from '../elements/ExternalDocumentation';
 import ItemsElement from '../elements/Items';
+import HeadersElement from '../elements/Headers';
 import ExampleElement from '../elements/Example';
 import HeaderElement from '../elements/Header';
 import TagElement from '../elements/Tag';
@@ -37,6 +38,13 @@ ExternalDocumentationElement.refract = createRefractor([
   '$visitor',
 ]);
 ItemsElement.refract = createRefractor(['visitors', 'document', 'objects', 'Items', '$visitor']);
+HeadersElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Headers',
+  '$visitor',
+]);
 ExampleElement.refract = createRefractor([
   'visitors',
   'document',
@@ -76,6 +84,7 @@ export {
   ContactElement,
   ExternalDocumentationElement,
   ItemsElement,
+  HeadersElement,
   ExampleElement,
   HeaderElement,
   TagElement,

diff --git a/packages/apidom-ns-openapi-2/src/refractor/specification.ts b/packages/apidom-ns-openapi-2/src/refractor/specification.ts
@@ -7,6 +7,7 @@ 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 ItemsVisitor from './visitors/open-api-2/items';
+import HeadersVisitor from './visitors/open-api-2/headers';
 import ExampleVisitor from './visitors/open-api-2/example';
 import HeaderVisitor from './visitors/open-api-2/header';
 import TagVisitor from './visitors/open-api-2/tag';
@@ -95,6 +96,9 @@ const specification = {
             multipleOf: jsonSchemaFixedFields.multipleOf,
           },
         },
+        Headers: {
+          $visitor: HeadersVisitor,
+        },
         Example: {
           $visitor: ExampleVisitor,
         },

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
@@ -3,11 +3,11 @@ import { always } from 'ramda';
 
 import ExampleElement from '../../../../elements/Example';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import MapVisitor from '../../generics/MapVisitor';
 
-const ExampleVisitor = stampit(FixedFieldsVisitor, FallbackVisitor, {
+const ExampleVisitor = stampit(MapVisitor, FallbackVisitor, {
   props: {
-    specPath: always(['document', 'objects', 'Example']),
+    specPath: always(['value']),
     canSupportSpecificationExtensions: false,
   },
   init() {

diff --git a/packages/apidom-ns-openapi-2/src/refractor/visitors/open-api-2/headers/index.ts b/packages/apidom-ns-openapi-2/src/refractor/visitors/open-api-2/headers/index.ts
@@ -0,0 +1,18 @@
+import stampit from 'stampit';
+import { always } from 'ramda';
+
+import MapVisitor from '../../generics/MapVisitor';
+import FallbackVisitor from '../../FallbackVisitor';
+import HeadersElement from '../../../../elements/Headers';
+
+const HeadersVisitor = stampit(MapVisitor, FallbackVisitor, {
+  props: {
+    specPath: always(['document', 'objects', 'Header']),
+    canSupportSpecificationExtensions: false,
+  },
+  init() {
+    this.element = new HeadersElement();
+  },
+});
+
+export default HeadersVisitor;
diff --git a/packages/apidom-ns-openapi-2/src/traversal/visitor.ts b/packages/apidom-ns-openapi-2/src/traversal/visitor.ts
@@ -25,6 +25,7 @@ export const keyMap = {
   ExternalDocumentationElement: ['content'],
   ItemsElement: ['content'],
   ExampleElement: ['content'],
+  HeadersElement: ['content'],
   HeaderElement: ['content'],
   TagElement: ['content'],
   XmlElement: ['content'],

diff --git a/packages/apidom-ns-openapi-2/test/predicates.ts b/packages/apidom-ns-openapi-2/test/predicates.ts
@@ -6,6 +6,7 @@ import {
   ContactElement,
   ExternalDocumentationElement,
   ItemsElement,
+  HeadersElement,
   ExampleElement,
   HeaderElement,
   TagElement,
@@ -19,6 +20,7 @@ import {
   isContactElement,
   isExternalDocumentationElement,
   isItemsElement,
+  isHeadersElement,
   isExampleElement,
   isHeaderElement,
   isTagElement,
@@ -41,7 +43,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class InfoSubElement extends InfoElement {}
 
         assert.isTrue(isInfoElement(new InfoSubElement()));
@@ -98,7 +99,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class LicenseSubElement extends LicenseElement {}
 
         assert.isTrue(isLicenseElement(new LicenseSubElement()));
@@ -155,7 +155,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class ContactSubElement extends ContactElement {}
 
         assert.isTrue(isContactElement(new ContactSubElement()));
@@ -212,7 +211,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class ExternalDocumentationSubElement extends ExternalDocumentationElement {}
 
         assert.isTrue(isExternalDocumentationElement(new ExternalDocumentationSubElement()));
@@ -269,7 +267,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class ItemsSubElement extends ItemsElement {}
 
         assert.isTrue(isItemsElement(new ItemsSubElement()));
@@ -315,6 +312,62 @@ describe('predicates', function () {
     });
   });
 
+  context('isHeadersElement', function () {
+    context('given HeadersElement instance value', function () {
+      specify('should return true', function () {
+        const element = new HeadersElement();
+
+        assert.isTrue(isHeadersElement(element));
+      });
+    });
+
+    context('given subtype instance value', function () {
+      specify('should return true', function () {
+        class HeadersSubElement extends HeadersElement {}
+
+        assert.isTrue(isHeadersElement(new HeadersSubElement()));
+      });
+    });
+
+    context('given non HeadersSubElement instance value', function () {
+      specify('should return false', function () {
+        assert.isFalse(isHeadersElement(1));
+        assert.isFalse(isHeadersElement(null));
+        assert.isFalse(isHeadersElement(undefined));
+        assert.isFalse(isHeadersElement({}));
+        assert.isFalse(isHeadersElement([]));
+        assert.isFalse(isHeadersElement('string'));
+      });
+    });
+
+    specify('should support duck-typing', function () {
+      const headersElementDuck = {
+        _storedElement: 'headers',
+        _content: [],
+        primitive() {
+          return 'object';
+        },
+        get element() {
+          return this._storedElement;
+        },
+      };
+
+      const headersElementSwan = {
+        _storedElement: undefined,
+        _content: undefined,
+        primitive() {
+          return 'swan';
+        },
+        get length() {
+          return 0;
+        },
+      };
+
+      assert.isTrue(isHeadersElement(headersElementDuck));
+      assert.isFalse(isHeadersElement(headersElementSwan));
+    });
+  });
+
   context('isExampleElement', function () {
     context('given ExampleElement instance value', function () {
       specify('should return true', function () {
@@ -326,7 +379,6 @@ describe('predicates', function () {
 
     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()));
@@ -383,7 +435,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class HeaderSubElement extends HeaderElement {}
 
         assert.isTrue(isHeaderElement(new HeaderSubElement()));
@@ -440,7 +491,6 @@ describe('predicates', function () {
 
     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()));
@@ -497,7 +547,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class XmlSubElement extends XmlElement {}
 
         assert.isTrue(isXmlElement(new XmlSubElement()));
@@ -554,7 +603,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class SecurityDefinitionsSubElement extends SecurityDefinitionsElement {}
 
         assert.isTrue(isSecurityDefinitionsElement(new SecurityDefinitionsSubElement()));
@@ -611,7 +659,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class SecuritySchemeSubElement extends SecuritySchemeElement {}
 
         assert.isTrue(isSecuritySchemeElement(new SecuritySchemeSubElement()));
@@ -668,7 +715,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class ScopesSubElement extends ScopesElement {}
 
         assert.isTrue(isScopesElement(new ScopesSubElement()));
@@ -725,7 +771,6 @@ describe('predicates', function () {
 
     context('given subtype instance value', function () {
       specify('should return true', function () {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
         class SecurityRequirementSubElement extends SecurityRequirementElement {}
 
         assert.isTrue(isSecurityRequirementElement(new SecurityRequirementSubElement()));

diff --git a/packages/apidom-ns-openapi-2/test/refractor/elements/Headers/__snapshots__/index.ts.snap b/packages/apidom-ns-openapi-2/test/refractor/elements/Headers/__snapshots__/index.ts.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`refractor elements HeadersElement should refract to semantic ApiDOM tree 1`] = `
+(HeadersElement
+  (MemberElement
+    (StringElement)
+    (HeaderElement))
+  (MemberElement
+    (StringElement)
+    (HeaderElement)))
+`;
diff --git a/packages/apidom-ns-openapi-2/test/refractor/elements/Headers/index.ts b/packages/apidom-ns-openapi-2/test/refractor/elements/Headers/index.ts
@@ -0,0 +1,19 @@
+import { expect } from 'chai';
+import { sexprs } from '@swagger-api/apidom-core';
+
+import { HeadersElement } from '../../../../src';
+
+describe('refractor', function () {
+  context('elements', function () {
+    context('HeadersElement', function () {
+      specify('should refract to semantic ApiDOM tree', function () {
+        const headersElement = HeadersElement.refract({
+          header1: {},
+          header2: {},
+        });
+
+        expect(sexprs(headersElement)).toMatchSnapshot();
+      });
+    });
+  });
+});