feat: conversion of openapi '3.0' to asyncapi '3.0' (#269)

Co-authored-by: Jonas Lagoni <jonas-lt@live.dk>

README.md

@@ -1,6 +1,6 @@
 # AsyncAPI Converter
 
-Convert [AsyncAPI](https://asyncapi.com) documents older to newer versions.
+Convert [AsyncAPI](https://asyncapi.com) documents older to newer versions and you can also convert OpenAPI documents to AsyncAPI documents.
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
@@ -17,6 +17,7 @@ Convert [AsyncAPI](https://asyncapi.com) documents older to newer versions.
   * [In TS](#in-ts)
 - [Conversion 2.x.x to 3.x.x](#conversion-2xx-to-3xx)
 - [Known missing features](#known-missing-features)
+- [OpenAPI 3.0 to AsyncAPI 3.0 Conversion](#openapi-30-to-asyncapi-30-conversion)
 - [Development](#development)
 - [Contribution](#contribution)
 - [Contributors ✨](#contributors-%E2%9C%A8)
@@ -194,6 +195,49 @@ Conversion to version `3.x.x` from `2.x.x` has several assumptions that should b
         examples: ["test"]
   ```
 
+### OpenAPI 3.0 to AsyncAPI 3.0 Conversion
+
+The converter now supports transformation from OpenAPI 3.0 to AsyncAPI 3.0. This feature enables easy transition of existing OpenAPI 3.0 documents to AsyncAPI 3.0.
+
+To use this new conversion feature:
+
+```js
+const fs = require('fs');
+const { convert } = require('@asyncapi/converter')
+
+try {
+  const openapi = fs.readFileSync('openapi.yml', 'utf-8')
+  const asyncapi = convert(openapi, '3.0.0', { from: 'openapi' });
+  console.log(asyncapi);
+} catch (e) {
+  console.error(e);
+}
+```
+
+When converting from OpenAPI to AsyncAPI you can now specify the perspective of the conversion using the `perspective` option. This allows you to choose whether the conversion should be from an application or client point of view
+
+```js
+const { convert } = require('@asyncapi/converter')
+
+try {
+  const asyncapi2 = fs.readFileSync('asyncapi2.yml', 'utf-8')
+  const asyncapi3 = convert(asyncapi2, '3.0.0', { openAPIToAsyncAPI: { perspective: 'client' } });
+  console.log(asyncapi3);
+} catch (e) {
+  console.error(e);
+}
+```
+
+The perspective option can be set to either 'server' (default) or 'client'. 
+
+- With `server` perspective: `action` becomes `receive`
+
+- With `client` perspective: `action` becomes `send`
+
+#### Limitations
+
+- External to internal references: The converter does not support scenarios where an external schema file references internal components of the OpenAPI document. In such cases, manual adjustment of the converted document may be necessary.
+
 ## Development
 
 1. Setup project by installing dependencies `npm install`

src/convert.ts

@@ -3,25 +3,31 @@ import { dump } from 'js-yaml';
 import { converters as firstConverters } from "./first-version";
 import { converters as secondConverters } from "./second-version";
 import { converters as thirdConverters } from "./third-version";
+import { converters as openapiConverters } from "./openapi";
 
 import { serializeInput } from "./utils";
 
-import type { AsyncAPIDocument, ConvertVersion, ConvertOptions, ConvertFunction } from './interfaces';
+import type { AsyncAPIDocument, AsyncAPIConvertVersion, OpenAPIConvertVersion, ConvertOptions, ConvertFunction, ConvertOpenAPIFunction, OpenAPIDocument, OpenAPIToAsyncAPIOptions } from './interfaces';
 
 /**
  * Value for key (version) represents the function which converts specification from previous version to the given as key.
  */
-const converters: Record<string, ConvertFunction> = {
+const asyncAPIconverters: Record<string, ConvertFunction> = {
   ...firstConverters,
   ...secondConverters,
   ...thirdConverters,
 };
-const conversionVersions = Object.keys(converters);
 
-export function convert(asyncapi: string, version?: ConvertVersion, options?: ConvertOptions): string;
-export function convert(asyncapi: AsyncAPIDocument, version?: ConvertVersion, options?: ConvertOptions): AsyncAPIDocument;
-export function convert(asyncapi: string | AsyncAPIDocument, version: ConvertVersion = '2.6.0', options: ConvertOptions = {}): string | AsyncAPIDocument {
-  const { format, document } = serializeInput(asyncapi);
+const conversionVersions = Object.keys(asyncAPIconverters);
+
+export function convert(input: string, version: AsyncAPIConvertVersion, options?: ConvertOptions): string;
+export function convert(input: AsyncAPIDocument, version: AsyncAPIConvertVersion, options?: ConvertOptions): AsyncAPIDocument;
+export function convert(input: string | AsyncAPIDocument, version: AsyncAPIConvertVersion , options: ConvertOptions= {}): string | AsyncAPIDocument {
+  const { format, document } = serializeInput(input);
+
+  if ('openapi' in document) {
+    throw new Error('Cannot convert OpenAPI document. Use convertOpenAPI function instead.');
+  }
 
   const asyncapiVersion = document.asyncapi;
   let fromVersion = conversionVersions.indexOf(asyncapiVersion);
@@ -41,12 +47,34 @@ export function convert(asyncapi: string | AsyncAPIDocument, version: ConvertVer
   fromVersion++;
   let converted = document;
   for (let i = fromVersion; i <= toVersion; i++) {
-    const v = conversionVersions[i] as ConvertVersion;
-    converted = converters[v](converted, options);
+    const v = conversionVersions[i] as AsyncAPIConvertVersion;
+    converted = asyncAPIconverters[v](converted, options);
   }
 
   if (format === 'yaml') {
     return dump(converted, { skipInvalid: true });
   }
   return converted;
 }
+
+export function convertOpenAPI(input: string ,version: OpenAPIConvertVersion,options?: OpenAPIToAsyncAPIOptions): string;
+export function convertOpenAPI(input: OpenAPIDocument, version: OpenAPIConvertVersion ,options?: OpenAPIToAsyncAPIOptions): AsyncAPIDocument;
+export function convertOpenAPI(input: string | OpenAPIDocument, version: OpenAPIConvertVersion, options: OpenAPIToAsyncAPIOptions = {}): string | AsyncAPIDocument {
+
+  const { format, document } = serializeInput(input);
+  const openApiVersion = document.openapi;
+  const converterVersion = openApiVersion;
+
+  const openapiToAsyncapiConverter = openapiConverters[converterVersion as OpenAPIConvertVersion] as ConvertOpenAPIFunction;
+
+  if (!openapiToAsyncapiConverter) {
+    throw new Error(`We are not able to convert OpenAPI ${converterVersion} to AsyncAPI, please raise a feature request.`);
+  }
+
+  const convertedAsyncAPI = openapiToAsyncapiConverter(document as OpenAPIDocument, options);
+
+  if (format === "yaml") {
+    return dump(convertedAsyncAPI, { skipInvalid: true });
+  }
+  return convertedAsyncAPI;
+}

src/index.ts

@@ -1,3 +1,3 @@
 export { convert } from './convert';
 
-export type { AsyncAPIDocument, ConvertVersion, ConvertOptions } from './interfaces';
+export type { AsyncAPIDocument, AsyncAPIConvertVersion, OpenAPIConvertVersion, ConvertOptions } from './interfaces';

src/interfaces.ts

@@ -2,20 +2,29 @@
  * PUBLIC TYPES
  */
 export type AsyncAPIDocument = { asyncapi: string } & Record<string, any>;
-export type ConvertVersion = '1.1.0' | '1.2.0' | '2.0.0-rc1' | '2.0.0-rc2' | '2.0.0' | '2.1.0' | '2.2.0' | '2.3.0' | '2.4.0' | '2.5.0' | '2.6.0' | '3.0.0';
+export type OpenAPIDocument = { openapi: string } & Record<string, any>;
+export type AsyncAPIConvertVersion = '1.1.0' | '1.2.0' | '2.0.0-rc1' | '2.0.0-rc2' | '2.0.0' | '2.1.0' | '2.2.0' | '2.3.0' | '2.4.0' | '2.5.0' | '2.6.0' | '3.0.0';
+
+export type OpenAPIConvertVersion = '3.0.0';
 export type ConvertV2ToV3Options = {
   idGenerator?: (data: { asyncapi: AsyncAPIDocument, kind: 'channel' | 'operation' | 'message', key: string | number | undefined, path: Array<string | number>, object: any, parentId?: string }) => string,
   pointOfView?: 'application' | 'client',
   useChannelIdExtension?: boolean;
   convertServerComponents?: boolean;
   convertChannelComponents?: boolean;
 }
+
+export type OpenAPIToAsyncAPIOptions = {
+  perspective?: 'client' | 'server';
+};
 export type ConvertOptions = {
   v2tov3?: ConvertV2ToV3Options;
+  openAPIToAsyncAPI?: OpenAPIToAsyncAPIOptions;
 }
 
 /**
  * PRIVATE TYPES
  */
 export type ConvertFunction = (asyncapi: AsyncAPIDocument, options: ConvertOptions) => AsyncAPIDocument;
+export type ConvertOpenAPIFunction = (openapi: OpenAPIDocument, options: OpenAPIToAsyncAPIOptions) => AsyncAPIDocument;