feat(apidom-converter): add reference summary and description plugins (#3885)

This plugin removes the summary and description fields of Reference Object.

Refs #3697

Author: tekyu

packages/apidom-converter/src/strategies/openapi-3-1-to-openapi-3-0-3/index.ts

@@ -24,6 +24,8 @@ import type { ConverterOptions } from '../../options';
 import createToolbox from './toolbox';
 import infoSummaryRefractorPlugin from './refractor-plugins/info-summary';
 import licenseIdentifierRefractorPlugin from './refractor-plugins/license-identifier';
+import referenceDescriptionRefractorPlugin from './refractor-plugins/reference-description';
+import referenceSummaryRefractorPlugin from './refractor-plugins/reference-summary';
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const openAPI3_0_3MediaTypes = [
@@ -67,6 +69,8 @@ class OpenAPI31ToOpenAPI30ConvertStrategy extends ConvertStrategy {
         securityRequirementsEmptyRolesRefractorPlugin({ annotations }),
         infoSummaryRefractorPlugin({ annotations }),
         licenseIdentifierRefractorPlugin({ annotations }),
+        referenceDescriptionRefractorPlugin({ annotations }),
+        referenceSummaryRefractorPlugin({ annotations }),
       ],
       {
         toolboxCreator: createToolbox,

packages/apidom-converter/src/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-description.ts

@@ -0,0 +1,29 @@
+import { ReferenceElement } from '@swagger-api/apidom-ns-openapi-3-1';
+import { AnnotationElement } from '@swagger-api/apidom-core';
+
+type ReferenceDescriptionPluginOptions = {
+  annotations: AnnotationElement[];
+};
+
+const referenceDescriptionRefractorPlugin =
+  ({ annotations }: ReferenceDescriptionPluginOptions) =>
+  () => {
+    const annotation = new AnnotationElement(
+      'The "description" field of Reference Object is not supported in OpenAPI 3.0.3. It has been removed from the converted document.',
+      { classes: ['warning'] },
+      { code: 'reference-description' },
+    );
+
+    return {
+      visitor: {
+        ReferenceElement(element: ReferenceElement) {
+          if (element.hasKey('description')) {
+            annotations.push(annotation);
+            element.remove('description');
+          }
+        },
+      },
+    };
+  };
+
+export default referenceDescriptionRefractorPlugin;

packages/apidom-converter/src/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-summary.ts

@@ -0,0 +1,29 @@
+import { ReferenceElement } from '@swagger-api/apidom-ns-openapi-3-1';
+import { AnnotationElement } from '@swagger-api/apidom-core';
+
+type ReferenceSummaryPluginOptions = {
+  annotations: AnnotationElement[];
+};
+
+const referenceSummaryRefractorPlugin =
+  ({ annotations }: ReferenceSummaryPluginOptions) =>
+  () => {
+    const annotation = new AnnotationElement(
+      'The "summary" field of Reference Object is not supported in OpenAPI 3.0.3. It has been removed from the converted document.',
+      { classes: ['warning'] },
+      { code: 'reference-summary' },
+    );
+
+    return {
+      visitor: {
+        ReferenceElement(element: ReferenceElement) {
+          if (element.hasKey('summary')) {
+            annotations.push(annotation);
+            element.remove('summary');
+          }
+        },
+      },
+    };
+  };
+
+export default referenceSummaryRefractorPlugin;

packages/apidom-converter/test/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-description/__snapshots__/index.ts.snap

@@ -0,0 +1,25 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`converter strategies openapi-3-1-to-openapi-3-0-3 reference-description should remove Reference.description field 1`] = `
+{
+  "openapi": "3.0.3",
+  "paths": {
+    "/path": {
+      "get": {
+        "responses": {
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "responses": {
+      "default": {
+        "description": "first response object"
+      }
+    }
+  }
+}
+`;

packages/apidom-converter/test/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-description/fixtures/reference-description.json

@@ -0,0 +1,22 @@
+{
+  "openapi": "3.1.0",
+  "paths": {
+    "/path": {
+      "get": {
+        "responses": {
+          "default": {
+            "$ref": "#/components/responses/default",
+            "description": "example description"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "responses": {
+      "default": {
+        "description": "first response object"
+      }
+    }
+  }
+}

packages/apidom-converter/test/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-description/index.ts

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import { expect, assert } from 'chai';
+import { mediaTypes as openAPI31MediaTypes } from '@swagger-api/apidom-parser-adapter-openapi-json-3-1';
+import { mediaTypes as openAPI30MediaTypes } from '@swagger-api/apidom-parser-adapter-openapi-json-3-0';
+import {
+  AnnotationElement,
+  ParseResultElement,
+  toJSON,
+  includesClasses,
+} from '@swagger-api/apidom-core';
+
+import convert from '../../../../../src';
+
+describe('converter', function () {
+  context('strategies', function () {
+    context('openapi-3-1-to-openapi-3-0-3', function () {
+      context('reference-description', function () {
+        const fixturePath = path.join(__dirname, 'fixtures', 'reference-description.json');
+        let convertedParseResult: ParseResultElement;
+
+        beforeEach(async function () {
+          convertedParseResult = await convert(fixturePath, {
+            convert: {
+              sourceMediaType: openAPI31MediaTypes.findBy('3.1.0', 'json'),
+              targetMediaType: openAPI30MediaTypes.findBy('3.0.3', 'json'),
+            },
+          });
+        });
+
+        specify('should remove Reference.description field', async function () {
+          expect(toJSON(convertedParseResult.api!, undefined, 2)).toMatchSnapshot();
+        });
+
+        specify('should create WARNING annotation for description field', async function () {
+          const annotations = Array.from(convertedParseResult.annotations);
+          const annotation = annotations.find((a: AnnotationElement) =>
+            a.code?.equals('reference-description'),
+          );
+
+          assert.isDefined(annotation);
+          assert.isTrue(includesClasses(['warning'], annotation));
+        });
+      });
+    });
+  });
+});

packages/apidom-converter/test/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-summary/__snapshots__/index.ts.snap

@@ -0,0 +1,25 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`converter strategies openapi-3-1-to-openapi-3-0-3 reference-summary should remove Reference.summary field 1`] = `
+{
+  "openapi": "3.0.3",
+  "paths": {
+    "/path": {
+      "get": {
+        "responses": {
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "responses": {
+      "default": {
+        "description": "first response object"
+      }
+    }
+  }
+}
+`;

packages/apidom-converter/test/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-summary/fixtures/reference-summary.json

@@ -0,0 +1,22 @@
+{
+  "openapi": "3.1.0",
+  "paths": {
+    "/path": {
+      "get": {
+        "responses": {
+          "default": {
+            "$ref": "#/components/responses/default",
+            "summary": "example summary"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "responses": {
+      "default": {
+        "description": "first response object"
+      }
+    }
+  }
+}

packages/apidom-converter/test/strategies/openapi-3-1-to-openapi-3-0-3/refractor-plugins/reference-summary/index.ts

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import { expect, assert } from 'chai';
+import { mediaTypes as openAPI31MediaTypes } from '@swagger-api/apidom-parser-adapter-openapi-json-3-1';
+import { mediaTypes as openAPI30MediaTypes } from '@swagger-api/apidom-parser-adapter-openapi-json-3-0';
+import {
+  AnnotationElement,
+  ParseResultElement,
+  toJSON,
+  includesClasses,
+} from '@swagger-api/apidom-core';
+
+import convert from '../../../../../src';
+
+describe('converter', function () {
+  context('strategies', function () {
+    context('openapi-3-1-to-openapi-3-0-3', function () {
+      context('reference-summary', function () {
+        const fixturePath = path.join(__dirname, 'fixtures', 'reference-summary.json');
+        let convertedParseResult: ParseResultElement;
+
+        beforeEach(async function () {
+          convertedParseResult = await convert(fixturePath, {
+            convert: {
+              sourceMediaType: openAPI31MediaTypes.findBy('3.1.0', 'json'),
+              targetMediaType: openAPI30MediaTypes.findBy('3.0.3', 'json'),
+            },
+          });
+        });
+
+        specify('should remove Reference.summary field', async function () {
+          expect(toJSON(convertedParseResult.api!, undefined, 2)).toMatchSnapshot();
+        });
+
+        specify('should create WARNING annotation for summary field', async function () {
+          const annotations = Array.from(convertedParseResult.annotations);
+          const annotation = annotations.find((a: AnnotationElement) =>
+            a.code?.equals('reference-summary'),
+          );
+
+          assert.isDefined(annotation);
+          assert.isTrue(includesClasses(['warning'], annotation));
+        });
+      });
+    });
+  });
+});