feat: Add support for ESM generation in openapi generator (#4883)

.changeset/five-carrots-whisper.md

@@ -0,0 +1,6 @@
+---
+'@sap-cloud-sdk/openapi-generator': minor
+'@sap-cloud-sdk/generator-common': minor
+---
+
+[New Functionality] Introduce option `generateESM` in OpenAPI generator to generate ESM compatible code.

packages/generator-common/src/file-writer/create-file.ts

@@ -32,6 +32,10 @@ export interface CreateFileOptions {
    * Flag to indicate if the file is formatted using prettier - Default is true.
    */
   usePrettier?: boolean;
+  /**
+   * Flag to indicate if the file is generated as ESM.
+   */
+  generateESM?: boolean;
 }
 
 /**

packages/generator-common/src/options.ts

@@ -112,7 +112,6 @@ export function getCommonCliOptions(serviceType: ServiceType) {
       type: 'boolean',
       default: false
     },
-
     readme: {
       type: 'boolean',
       describe: getReadmeText(serviceType),

packages/openapi-generator/src/file-serializer/__snapshots__/api-file.spec.ts.snap

@@ -0,0 +1,126 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`api-file creates an api file following the esm pattern 1`] = `
+"import { OpenApiRequestBuilder } from '@sap-cloud-sdk/openapi';
+import type { QueryParameterType, RefType, ResponseType } from './schema/index.js';
+/**
+ * Representation of the 'TestApi'.
+ * This API is part of the 'MyServiceName' service.
+ */
+export const TestApi = {
+  /**
+   * Create a request builder for execution of get requests to the 'test/{id}' endpoint.
+   * @param id - Path parameter.
+   * @param queryParameters - Object containing the following keys: queryParam.
+   * @param headerParameters - Object containing the following keys: headerParam.
+   * @returns The request builder, use the \`execute()\` method to trigger the request.
+   */
+  getFn: (id: string, queryParameters: {'queryParam': QueryParameterType}, headerParameters?: {'headerParam'?: string}) => new OpenApiRequestBuilder<string>(
+    'get',
+    "test/{id}",
+    {
+          pathParameters: { id },
+          queryParameters,
+          headerParameters
+        }
+  ),
+  /**
+   * Create a request builder for execution of post requests to the 'test' endpoint.
+   * @param body - Request body.
+   * @returns The request builder, use the \`execute()\` method to trigger the request.
+   */
+  createFn: (body: RefType) => new OpenApiRequestBuilder<ResponseType>(
+    'post',
+    "test",
+    {
+          body
+        }
+  )
+};"
+`;
+
+exports[`api-file creates an api file with documentation 1`] = `
+"import { OpenApiRequestBuilder } from '@sap-cloud-sdk/openapi';
+/**
+ * Representation of the 'TestApi'.
+ * This API is part of the 'TestService' service.
+ */
+export const TestApi = {
+  /**
+   * Create a request builder for execution of get requests to the 'test' endpoint.
+   * @returns The request builder, use the \`execute()\` method to trigger the request.
+   */
+  getFn: () => new OpenApiRequestBuilder<any>(
+    'get',
+    "test"
+  )
+};"
+`;
+
+exports[`api-file creates documentation for the api 1`] = `
+"/**
+ * Representation of the 'TestApi'.
+ * This API is part of the 'TestService' service.
+ */"
+`;
+
+exports[`api-file serializes api file with multiple operations and references 1`] = `
+"import { OpenApiRequestBuilder } from '@sap-cloud-sdk/openapi';
+import type { QueryParameterType, RefType, ResponseType } from './schema';
+/**
+ * Representation of the 'TestApi'.
+ * This API is part of the 'MyServiceName' service.
+ */
+export const TestApi = {
+  /**
+   * Create a request builder for execution of get requests to the 'test/{id}' endpoint.
+   * @param id - Path parameter.
+   * @param queryParameters - Object containing the following keys: queryParam.
+   * @param headerParameters - Object containing the following keys: headerParam.
+   * @returns The request builder, use the \`execute()\` method to trigger the request.
+   */
+  getFn: (id: string, queryParameters: {'queryParam': QueryParameterType}, headerParameters?: {'headerParam'?: string}) => new OpenApiRequestBuilder<string>(
+    'get',
+    "test/{id}",
+    {
+          pathParameters: { id },
+          queryParameters,
+          headerParameters
+        }
+  ),
+  /**
+   * Create a request builder for execution of post requests to the 'test' endpoint.
+   * @param body - Request body.
+   * @returns The request builder, use the \`execute()\` method to trigger the request.
+   */
+  createFn: (body: RefType) => new OpenApiRequestBuilder<ResponseType>(
+    'post',
+    "test",
+    {
+          body
+        }
+  )
+};"
+`;
+
+exports[`api-file serializes api file with one operation and no references 1`] = `
+"import { OpenApiRequestBuilder } from '@sap-cloud-sdk/openapi';
+/**
+ * Representation of the 'TestApi'.
+ * This API is part of the 'MyServiceName' service.
+ */
+export const TestApi = {
+  /**
+   * Create a request builder for execution of get requests to the 'test/{id}' endpoint.
+   * @param id - Path parameter.
+   * @returns The request builder, use the \`execute()\` method to trigger the request.
+   */
+  getFn: (id: string) => new OpenApiRequestBuilder<any>(
+    'get',
+    "test/{id}",
+    {
+          pathParameters: { id }
+        }
+  )
+};"
+`;

packages/openapi-generator/src/file-serializer/__snapshots__/index-file.spec.ts.snap

@@ -0,0 +1,28 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`index-file apiIndexFile serializes the api index file following the esm format 1`] = `
+"    export * from './test-api.js';
+    export * from './default-api.js';
+    export * from './schema/index.js';"
+`;
+
+exports[`index-file apiIndexFile serializes the api index file with referenced schemas 1`] = `
+"    export * from './test-api';
+    export * from './default-api';
+    export * from './schema';"
+`;
+
+exports[`index-file apiIndexFile serializes the api index file without referenced schemas 1`] = `
+"    export * from './test-api';
+    export * from './default-api';"
+`;
+
+exports[`index-file schemaIndexFile serializes the schema index file for schemas following the ESM format 1`] = `
+"export * from './my-schema-1.js';
+export * from './some-other-name.js';"
+`;
+
+exports[`index-file schemaIndexFile serializes the schema index file for schemas in a document 1`] = `
+"export * from './my-schema-1';
+export * from './some-other-name';"
+`;

packages/openapi-generator/src/file-serializer/__snapshots__/schema-file.spec.ts.snap

@@ -0,0 +1,90 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`schemaFile creates a schema property documentation 1`] = `
+"/**
+ * My property Description.
+ */"
+`;
+
+exports[`schemaFile creates schema documentation 1`] = `
+"/**
+ * Representation of the 'mySchema' schema.
+ */"
+`;
+
+exports[`schemaFile serializes schema file for schema 1`] = `
+"    
+    /**
+     * Representation of the 'MySchema' schema.
+     * @deprecated
+     */
+    export type MySchema = {
+      /**
+       * Max Length: 10.
+       */
+      'string-property': string;
+    };"
+`;
+
+exports[`schemaFile serializes schema file for schema including ESM references 1`] = `
+"    import type { OtherSchema1 } from './other-schema-1.js';
+    import type { OtherSchema2 } from './other-schema-2.js';
+    /**
+     * Representation of the 'MySchema' schema.
+     */
+    export type MySchema = {
+      'otherSchema1': OtherSchema1;
+      /**
+       * Description other Schema 2
+       */
+      'otherSchema2': OtherSchema2;
+    };"
+`;
+
+exports[`schemaFile serializes schema file for schema including not schema 1`] = `
+"    
+    /**
+     * Representation of the 'MySchema' schema.
+     */
+    export type MySchema = any[];"
+`;
+
+exports[`schemaFile serializes schema file for schema including references 1`] = `
+"    import type { OtherSchema1 } from './other-schema-1';
+    import type { OtherSchema2 } from './other-schema-2';
+    /**
+     * Representation of the 'MySchema' schema.
+     */
+    export type MySchema = {
+      'otherSchema1': OtherSchema1;
+      /**
+       * Description other Schema 2
+       */
+      'otherSchema2': OtherSchema2;
+    };"
+`;
+
+exports[`schemaFile serializes schema file without imports for schema including only self reference 1`] = `
+"    
+    /**
+     * Representation of the 'MySchema' schema.
+     */
+    export type MySchema = {
+      'property'?: MySchema;
+    };"
+`;
+
+exports[`schemaFile serializes simple schema file for schema with description 1`] = `
+"    
+    /**
+     * Representation of the 'MySchema' schema.
+     */
+    export type MySchema = {
+      /**
+       * My description
+       * Min Length: 2.
+       */
+      'string-property': string;
+      'string-property-no-description': string;
+    };"
+`;