fix: sdk exploded syntax - make parameter serialization optional

sdo-1A · sdo-1A · commit aea43f60e089 · 2025-04-09T14:04:28.000+02:00
diff --git a/packages/@ama-sdk/client-angular/src/api-angular-client.ts b/packages/@ama-sdk/client-angular/src/api-angular-client.ts
@@ -55,7 +55,8 @@ const DEFAULT_OPTIONS = {
   angularPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 } as const satisfies Omit<BaseApiAngularClientOptions, 'basePath' | 'httpClient'>;
 
 /** Client to process the call to the API using Angular API */
diff --git a/packages/@ama-sdk/client-beacon/src/api-beacon-client.ts b/packages/@ama-sdk/client-beacon/src/api-beacon-client.ts
@@ -35,7 +35,8 @@ export interface BaseApiBeaconClientConstructor extends PartialExcept<Omit<BaseA
 const DEFAULT_OPTIONS = {
   replyPlugins: [] as never[],
   requestPlugins: [],
-  enableTokenization: false
+  enableTokenization: false,
+  enableParameterSerialization: false
 } as const satisfies Omit<BaseApiBeaconClientOptions, 'basePath'>;
 
 /**
diff --git a/packages/@ama-sdk/client-fetch/src/api-fetch-client.ts b/packages/@ama-sdk/client-fetch/src/api-fetch-client.ts
@@ -51,7 +51,8 @@ const DEFAULT_OPTIONS = {
   fetchPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 } as const satisfies Omit<BaseApiFetchClientOptions, 'basePath'>;
 
 /** Client to process the call to the API using Fetch API */
diff --git a/packages/@ama-sdk/core/src/clients/api-angular-client.ts b/packages/@ama-sdk/core/src/clients/api-angular-client.ts
@@ -82,7 +82,8 @@ const DEFAULT_OPTIONS: Omit<BaseApiAngularClientOptions, 'basePath' | 'httpClien
   angularPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 };
 
 /**
diff --git a/packages/@ama-sdk/core/src/clients/api-beacon-client.ts b/packages/@ama-sdk/core/src/clients/api-beacon-client.ts
@@ -52,7 +52,8 @@ export interface BaseApiBeaconClientConstructor extends PartialExcept<Omit<BaseA
 const DEFAULT_OPTIONS: Omit<BaseApiBeaconClientOptions, 'basePath'> = {
   replyPlugins: [] as never[],
   requestPlugins: [],
-  enableTokenization: false
+  enableTokenization: false,
+  enableParameterSerialization: false
 };
 
 /**
diff --git a/packages/@ama-sdk/core/src/clients/api-fetch-client.ts b/packages/@ama-sdk/core/src/clients/api-fetch-client.ts
@@ -73,7 +73,8 @@ const DEFAULT_OPTIONS: Omit<BaseApiFetchClientOptions, 'basePath'> = {
   fetchPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 };
 
 /**
diff --git a/packages/@ama-sdk/core/src/fwk/api.helpers.ts b/packages/@ama-sdk/core/src/fwk/api.helpers.ts
@@ -13,7 +13,6 @@ import type {
  * Prepares the url to be called
  * @param url Base url to be used
  * @param queryParameters Key value pair with the parameters. If the value is undefined, the key is dropped
- * @deprecated use {@link prepareUrlWithQueryParams} with query parameter serialization, will be removed in v14.
  */
 export function prepareUrl(url: string, queryParameters: { [key: string]: string | undefined } = {}) {
   const queryPart = Object.keys(queryParameters)
diff --git a/packages/@ama-sdk/core/src/fwk/core/api-client.ts b/packages/@ama-sdk/core/src/fwk/core/api-client.ts
@@ -1,4 +1,5 @@
 import type {
+  ParamSerializationOptions,
   RequestBody,
   RequestMetadata,
   RequestOptions,
@@ -27,8 +28,8 @@ export interface RequestOptionsParameters {
   basePath: string;
   /** Query Parameters */
   queryParams?: { [key: string]: string | undefined };
-  /** Serialization of the query parameters (style and explode) */
-  queryParamSerialization?: { [key: string]: ParamSerialization };
+  /** Parameter serialization options */
+  paramSerializationOptions?: ParamSerializationOptions;
   /** Force body to string */
   body?: RequestBody;
   /** Force headers to Headers type */
diff --git a/packages/@ama-sdk/core/src/fwk/core/base-api-constructor.ts b/packages/@ama-sdk/core/src/fwk/core/base-api-constructor.ts
@@ -27,6 +27,8 @@ export interface BaseApiClientOptions {
   disableFallback?: boolean;
   /** Logger (optional, fallback to console logger if undefined) */
   logger?: Logger;
+  /** Enable parameter serialization with exploded syntax */
+  enableParameterSerialization?: boolean;
   /** Custom query parameter serialization method */
   serializeQueryParams?<T extends { [key: string]: SupportedParamType }>(queryParams: T, queryParamSerialization: { [p in keyof T]: ParamSerialization }): { [p in keyof T]: string };
   /** Custom query parameter serialization method */
diff --git a/packages/@ama-sdk/core/src/fwk/param-serialization.ts b/packages/@ama-sdk/core/src/fwk/param-serialization.ts
@@ -47,14 +47,7 @@ export type QueryParamValueSerialization = { value: SupportedParamType } & Param
  * Serialize query parameters of request plugins
  * @param queryParams
  */
-export function serializeRequestPluginQueryParams(queryParams: { [key: string]: string } | { [key: string]: QueryParamValueSerialization }) {
-  // NOTE: Check if the type of the property values of `queryParams` is string
-  if (isParamValueRecord(queryParams)) {
-    return Object.entries(queryParams).reduce((acc, [paramKey, paramValue]) => {
-      acc[paramKey] = `${paramKey}=${paramValue}`;
-      return acc;
-    }, {} as { [key: string]: string });
-  }
+export function serializeRequestPluginQueryParams(queryParams: { [key: string]: QueryParamValueSerialization }) {
   const queryParamsValues: { [key: string]: SupportedParamType } = {};
   const queryParamSerialization: { [key: string]: ParamSerialization } = {};
   Object.entries(queryParams).forEach(([paramKey, paramValue]) => {
diff --git a/packages/@ama-sdk/core/src/plugins/additional-params/additional-params-sync.request.ts b/packages/@ama-sdk/core/src/plugins/additional-params/additional-params-sync.request.ts
@@ -1,4 +1,5 @@
 import {
+  isParamValueRecord,
   type QueryParamValueSerialization,
   serializeRequestPluginQueryParams,
 } from '../../fwk/param-serialization';
@@ -43,7 +44,11 @@ export class AdditionalParamsSyncRequest implements RequestPlugin {
         const body = this.additionalParams.body && isStringOrUndefined(data.body) ? this.additionalParams.body(data.body) : undefined;
 
         if (queryParams) {
-          data.queryParams = { ...data.queryParams, ...serializeRequestPluginQueryParams(queryParams) };
+          if (data.paramSerializationOptions?.enableParameterSerialization && !isParamValueRecord(queryParams)) {
+            data.queryParams = { ...data.queryParams, ...serializeRequestPluginQueryParams(queryParams) };
+          } else if (isParamValueRecord(queryParams)) {
+            data.queryParams = { ...data.queryParams, ...queryParams };
+          }
         }
 
         if (body !== undefined) {
diff --git a/packages/@ama-sdk/core/src/plugins/additional-params/additional-params.request.ts b/packages/@ama-sdk/core/src/plugins/additional-params/additional-params.request.ts
@@ -1,4 +1,5 @@
 import {
+  isParamValueRecord,
   type QueryParamValueSerialization,
   serializeRequestPluginQueryParams,
 } from '../../fwk/param-serialization';
@@ -52,7 +53,11 @@ export class AdditionalParamsRequest implements RequestPlugin {
         const body = this.additionalParams.body && isStringOrUndefined(data.body) ? this.additionalParams.body(data.body) : undefined;
 
         if (queryParams) {
-          data.queryParams = { ...data.queryParams, ...serializeRequestPluginQueryParams(queryParams) };
+          if (data.paramSerializationOptions?.enableParameterSerialization && !isParamValueRecord(queryParams)) {
+            data.queryParams = { ...data.queryParams, ...serializeRequestPluginQueryParams(queryParams) };
+          } else if (isParamValueRecord(queryParams)) {
+            data.queryParams = { ...data.queryParams, ...queryParams };
+          }
         }
 
         if (body !== undefined) {
diff --git a/packages/@ama-sdk/core/src/plugins/additional-params/additional-params.spec.ts b/packages/@ama-sdk/core/src/plugins/additional-params/additional-params.spec.ts
@@ -12,7 +12,7 @@ describe('Additional Params Request Plugin', () => {
   const additionalGetParams = jest.fn().mockReturnValue({ test: 'ok' });
   const additionalBody = jest.fn().mockReturnValue('newBody');
 
-  const defaultGetParams = { defaultTest: 'defaultTest=ok' };
+  const defaultGetParams = { defaultTest: 'ok' };
   const defaultBody = 'default';
   let options: RequestOptions;
 
@@ -32,10 +32,11 @@ describe('Additional Params Request Plugin', () => {
 
     const result = await runner.transform(options);
 
-    expect(result.queryParams.test).toBe('test=ok');
+    expect(result.queryParams.test).toBe('ok');
   });
 
   it('should add serialized query params', async () => {
+    options.paramSerializationOptions = { enableParameterSerialization: true };
     const plugin = new AdditionalParamsRequest({ queryParams:
       {
         primParam: { value: 'ok', explode: false, style: 'form' },
@@ -48,7 +49,7 @@ describe('Additional Params Request Plugin', () => {
     const result = await runner.transform(options);
 
     expect(result.queryParams).toStrictEqual({
-      defaultTest: 'defaultTest=ok',
+      defaultTest: 'ok',
       primParam: 'primParam=ok',
       arrParam: 'arrParam=a%20b%20c',
       objParam: 'objParam%5Bprop1%5D=value1&objParam%5Bprop2%5D=value2'
@@ -62,7 +63,7 @@ describe('Additional Params Request Plugin', () => {
     const result = await runner.transform(options);
 
     expect(additionalGetParams).toHaveBeenCalledWith(defaultGetParams);
-    expect(result.queryParams.test).toBe('test=ok');
+    expect(result.queryParams.test).toBe('ok');
   });
 
   it('should modify body', async () => {
@@ -72,7 +73,7 @@ describe('Additional Params Request Plugin', () => {
     const result = await runner.transform(options);
 
     expect(result.queryParams.test).toBeUndefined();
-    expect(result.queryParams.defaultTest).toBe('defaultTest=ok');
+    expect(result.queryParams.defaultTest).toBe('ok');
 
     expect(additionalBody).toHaveBeenCalledWith(defaultBody);
     expect(result.body).toBe('newBody');
@@ -83,7 +84,7 @@ describe('Additional Params Request Sync Plugin', () => {
   const additionalGetParams = jest.fn().mockReturnValue({ test: 'ok' });
   const additionalBody = jest.fn().mockReturnValue('newBody');
 
-  const defaultGetParams = { defaultTest: 'defaultTest=ok' };
+  const defaultGetParams = { defaultTest: 'ok' };
   const defaultBody = 'default';
   let options: RequestOptions;
 
@@ -103,10 +104,11 @@ describe('Additional Params Request Sync Plugin', () => {
 
     const result = runner.transform(options);
 
-    expect(result.queryParams.test).toBe('test=ok');
+    expect(result.queryParams.test).toBe('ok');
   });
 
   it('should add serialized query params', () => {
+    options.paramSerializationOptions = { enableParameterSerialization: true };
     const plugin = new AdditionalParamsSyncRequest({ queryParams:
         {
           primParam: { value: 'ok', explode: false, style: 'form' },
@@ -119,7 +121,7 @@ describe('Additional Params Request Sync Plugin', () => {
     const result = runner.transform(options);
 
     expect(result.queryParams).toStrictEqual({
-      defaultTest: 'defaultTest=ok',
+      defaultTest: 'ok',
       primParam: 'primParam=ok',
       arrParam: 'arrParam=a%20b%20c',
       objParam: 'objParam%5Bprop1%5D=value1&objParam%5Bprop2%5D=value2'
@@ -133,7 +135,7 @@ describe('Additional Params Request Sync Plugin', () => {
     const result = runner.transform(options);
 
     expect(additionalGetParams).toHaveBeenCalledWith(defaultGetParams);
-    expect(result.queryParams.test).toBe('test=ok');
+    expect(result.queryParams.test).toBe('ok');
   });
 
   it('should modify body', () => {
@@ -143,7 +145,7 @@ describe('Additional Params Request Sync Plugin', () => {
     const result = runner.transform(options);
 
     expect(result.queryParams.test).toBeUndefined();
-    expect(result.queryParams.defaultTest).toBe('defaultTest=ok');
+    expect(result.queryParams.defaultTest).toBe('ok');
 
     expect(additionalBody).toHaveBeenCalledWith(defaultBody);
     expect(result.body).toBe('newBody');
diff --git a/packages/@ama-sdk/core/src/plugins/core/request-plugin.ts b/packages/@ama-sdk/core/src/plugins/core/request-plugin.ts
@@ -1,5 +1,6 @@
 import type {
   Api,
+  ParamSerialization,
 } from '../../fwk';
 import type {
   Plugin,
@@ -44,9 +45,21 @@ export interface RequestMetadata<C extends string = string, A extends string = s
   signal?: AbortSignal;
 }
 
+/**
+ * Options for the serialization of the parameters
+ */
+export interface ParamSerializationOptions {
+  /** Serialization of the query parameters (style and explode) */
+  queryParamSerialization?: { [key: string]: ParamSerialization };
+  /** Enable parameter serialization with exploded syntax */
+  enableParameterSerialization?: boolean;
+}
+
 export interface RequestOptions extends RequestInit {
   /** Query Parameters */
   queryParams?: { [key: string]: string };
+  /** Parameter serialization options */
+  paramSerializationOptions?: ParamSerializationOptions;
   /** Force body to string */
   body?: RequestBody;
   /** Force headers to Headers type */
diff --git a/packages/@ama-sdk/core/src/plugins/json-token/json-token.spec.ts b/packages/@ama-sdk/core/src/plugins/json-token/json-token.spec.ts
@@ -16,7 +16,7 @@ describe('Json Token', () => {
   const tokenKey = 'testToken';
 
   describe('request plugin', () => {
-    const defaultGetParams = { defaultTest: 'defaultTest=ok' };
+    const defaultGetParams = { defaultTest: 'ok' };
     const defaultBody = 'default';
     let options: RequestOptions;
 
diff --git a/packages/@ama-sdk/core/src/plugins/si-token/si-token.spec.ts b/packages/@ama-sdk/core/src/plugins/si-token/si-token.spec.ts
@@ -6,7 +6,7 @@ import {
 } from './si-token.request';
 
 describe('SI Token Request Plugin', () => {
-  const defaultGetParams = { defaultTest: 'defaultTest=ok' };
+  const defaultGetParams = { defaultTest: 'ok' };
   const defaultBody = 'default';
   let options: RequestOptions;
 
@@ -26,7 +26,7 @@ describe('SI Token Request Plugin', () => {
 
     const result = await runner.transform(options);
 
-    expect(result.queryParams.SITK).toBe('SITK=SIToken1');
-    expect(result.queryParams.SITK2).toBe('SITK2=SIToken2');
+    expect(result.queryParams.SITK).toBe('SIToken1');
+    expect(result.queryParams.SITK2).toBe('SIToken2');
   });
 });
diff --git a/packages/@ama-sdk/core/src/plugins/url-rewrite/url-rewrite.spec.ts b/packages/@ama-sdk/core/src/plugins/url-rewrite/url-rewrite.spec.ts
@@ -8,7 +8,7 @@ import {
 describe('URL Rewrite Request Plugin', () => {
   const urlRewriter = jest.fn().mockReturnValue('http://ok');
 
-  const defaultGetParams = { defaultTest: 'defaultTest=ok' };
+  const defaultGetParams = { defaultTest: 'ok' };
   const defaultBody = 'default';
   const defaultUrl = 'http://test.com/truc';
   let options: RequestOptions;
diff --git a/packages/@ama-sdk/schematics/README.md b/packages/@ama-sdk/schematics/README.md
@@ -119,6 +119,16 @@ For more information, check out OpenAPI's documentation on [parameter serializat
 It is important to note that, as in OpenAPI 3.1, we only support simple arrays and simple non-nested objects in path and query parameters. 
 The parameter types that we support are stored in `SupportedParamType` in the package `@ama-sdk/core`.
 
+To enable the parameter serialization within your API, you can set the option `enableParameterSerialization` to `true` (its current default value is `false`) in the constructor. For example:
+```typescript
+const apiConfig: ApiClient = new ApiFetchClient(
+  {
+    basePath: 'https://petstore3.swagger.io/api/v3',
+    enableParameterSerialization: true
+  }
+);
+```
+
 We provide the methods `serializeQueryParams` and `serializePathParams` to serialize the values of query and path parameters. However, it is also possible to pass
 your own serialization methods if the ones provided do not meet your requirements. These custom methods can be passed as a parameter to the API client constructor.
 
diff --git a/packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/java/com/amadeus/codegen/ts/AbstractTypeScriptClientCodegen.java b/packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/java/com/amadeus/codegen/ts/AbstractTypeScriptClientCodegen.java
@@ -146,7 +146,9 @@ public AbstractTypeScriptClientCodegen() {
     additionalProperties.put("parseRegexp", new LambdaHelper.ParseRegexp());
     additionalProperties.put("plurialize", new LambdaHelper.Plurialize());
     additionalProperties.put("urlParamReplacer", new LambdaHelper.UrlParamReplacerLambda());
+    additionalProperties.put("urlSerializedParamReplacer", new LambdaHelper.UrlSerializedParamReplacerLambda());
     additionalProperties.put("tokenizedUrlParamReplacer", new LambdaHelper.TokenizedUrlParamReplacerLambda());
+    additionalProperties.put("tokenizedUrlSerializedParamReplacer", new LambdaHelper.TokenizedUrlSerializedParamReplacerLambda());
     additionalProperties.put("apiFolderName", new LambdaHelper.ApiFolderName());
     additionalProperties.put("removeBrackets", new LambdaHelper.RemoveText("[]"));
     additionalProperties.put("removeFowardslash", new LambdaHelper.RemoveText("/"));
diff --git a/packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/java/com/amadeus/codegen/ts/LambdaHelper.java b/packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/java/com/amadeus/codegen/ts/LambdaHelper.java
@@ -59,12 +59,29 @@ public String formatFragment(String fragment) {
    * Replaces placeholders in the URL such as
    * /carts/{cartId}/travelers
    * to
-   * /carts/${serializedPathParams['cartId']}/travelers
+   * /carts/${data['cartId']}/travelers
    */
   public static class UrlParamReplacerLambda extends CustomLambda {
 
       public UrlParamReplacerLambda() {}
 
+      @Override
+      public String formatFragment(String fragment) {
+          return fragment.replaceAll("\\{([\\w_-]+)\\}", "\\${data['$1']}");
+      }
+
+  }
+
+  /**
+   * Replaces placeholders in the URL such as
+   * /carts/{cartId}/travelers
+   * to
+   * /carts/${serializedPathParams['cartId']}/travelers
+   */
+  public static class UrlSerializedParamReplacerLambda extends CustomLambda {
+
+      public UrlSerializedParamReplacerLambda() {}
+
       @Override
       public String formatFragment(String fragment) {
           return fragment.replaceAll("\\{([\\w_-]+)\\}", "\\${serializedPathParams['$1']}");
@@ -76,12 +93,28 @@ public String formatFragment(String fragment) {
    * Replaces placeholders in the URL such as
    * /carts/{cartId}/travelers
    * to
-   * /carts/${this.piiParamTokens['$1'] || serializedPathParams['$1']}/travelers
+   * /carts/${this.piiParamTokens['$1'] || data['$1']}/travelers
    */
   public static class TokenizedUrlParamReplacerLambda extends CustomLambda {
 
       public TokenizedUrlParamReplacerLambda() {}
 
+      @Override
+      public String formatFragment(String fragment) {
+          return fragment.replaceAll("\\{([\\w_-]+)\\}", "\\${this.piiParamTokens['$1'] || data['$1']}");
+      }
+  }
+
+  /**
+   * Replaces placeholders in the URL such as
+   * /carts/{cartId}/travelers
+   * to
+   * /carts/${this.piiParamTokens['$1'] || serializedPathParams['$1']}/travelers
+   */
+  public static class TokenizedUrlSerializedParamReplacerLambda extends CustomLambda {
+
+      public TokenizedUrlSerializedParamReplacerLambda() {}
+
       @Override
       public String formatFragment(String fragment) {
           return fragment.replaceAll("\\{([\\w_-]+)\\}", "\\${this.piiParamTokens['$1'] || serializedPathParams['$1']}");
diff --git a/packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/resources/typescriptFetch/api/api.mustache b/packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/resources/typescriptFetch/api/api.mustache
diff --git a/packages/@o3r-training/showcase-sdk/src/api/pet/pet-api.ts b/packages/@o3r-training/showcase-sdk/src/api/pet/pet-api.ts
diff --git a/packages/@o3r-training/showcase-sdk/src/api/store/store-api.ts b/packages/@o3r-training/showcase-sdk/src/api/store/store-api.ts
diff --git a/packages/@o3r-training/showcase-sdk/src/api/user/user-api.ts b/packages/@o3r-training/showcase-sdk/src/api/user/user-api.ts
diff --git a/packages/@o3r-training/training-sdk/src/api/dummy/dummy-api.ts b/packages/@o3r-training/training-sdk/src/api/dummy/dummy-api.ts
