feat(ama-sdk-generator): add guard function for extended definitions

feat(ama-sdk-generator): enhance extended model definition with discriminator literal type
feat(ama-sdk-generator): add discriminator extended list

Author: kpanot

nx.json

@@ -223,10 +223,14 @@
         "source",
         "specs"
       ],
-      "dependsOn": [{
-        "projects": ["test-helpers"],
-        "target": "build"
-      }],
+      "dependsOn": [
+        {
+          "projects": [
+            "test-helpers"
+          ],
+          "target": "build"
+        }
+      ],
       "outputs": [
         "{projectRoot}/dist-test/junit.xml",
         "{projectRoot}/coverage/cobertura-coverage.xml"
@@ -247,10 +251,14 @@
     },
     "test-int": {
       "executor": "@nx/jest:jest",
-      "dependsOn": [{
-        "projects": ["test-helpers"],
-        "target": "build"
-      }],
+      "dependsOn": [
+        {
+          "projects": [
+            "test-helpers"
+          ],
+          "target": "build"
+        }
+      ],
       "inputs": [
         {
           "env": "RUNNER_OS"
@@ -732,5 +740,6 @@
     "appsDir": "apps"
   },
   "cacheDirectory": ".cache/nx",
-  "nxCloudId": "63e6951e043da20dd8321aec"
-}
+  "nxCloudId": "63e6951e043da20dd8321aec",
+  "analytics": true
+}

packages/@ama-sdk/schematics/README.md

@@ -200,6 +200,26 @@ The Body request parameter generated in the SDK can also be defined in the speci
 > [!WARNING]
 > This vendor extension will take precedence over the global property `requestBodyTransform`.
 
+##### Dynamic Enums Type
+
+By default, enums are generated as static types. You can enable dynamic enum type generation by using the global property option `useDynamicEnumType` by adding `--global-property useDynamicEnumType=true` to the generator command.
+
+This option allows enums to be generated as dynamic types that can handle additional values not explicitly defined in the specification, making your SDK more resilient to API changes.
+
+Example:
+
+```shell
+yarn schematics @ama-sdk/schematics:typescript-core --spec-path ./swagger-spec.yaml --global-property useDynamicEnumType=true
+```
+
+##### Override Discriminator Type with Value
+
+By default, when a discriminator is used in the specification file, the children models are generated with a type that corresponds to the discriminator property and its value (for example, if the discriminator is `petType` and its value is `Dog`, the generated type for the children model will be `Dog`). You can enable the generation of the discriminator property as a type instead of its value by using the global property option `overrideDiscriminatorTypeWithValue` by adding `--global-property overrideDiscriminatorTypeWithValue=true` to the generator command.
+
+##### Children Model List Type Suffix
+
+The options `childrenModelListTypeSuffix` will add a suffix to the generated type of the list of children models when a discriminator is used in the specification file. If not specified the list of object children will not be generated.
+
 ##### Extensible models
 
 You may be in a case in which you want to be able to extend your SDK models and therefore ensure that revivers are generated

packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/java/com/amadeus/codegen/ts/AbstractTypeScriptClientCodegen.java

@@ -47,7 +47,10 @@ public abstract class AbstractTypeScriptClientCodegen extends DefaultCodegen imp
   private final boolean stringifyDate;
   private final boolean allowModelExtension;
   private final boolean useLegacyDateExtension;
+  private final boolean useDynamicEnumType;
+  private final boolean overrideDiscriminatorTypeWithValue;
   private final String requestBodyTransform;
+  private final String childrenModelListTypeSuffix;
 
   public AbstractTypeScriptClientCodegen() {
     super();
@@ -120,6 +123,12 @@ public AbstractTypeScriptClientCodegen() {
     stringifyDate = stringifyDateString != null ? !"false".equalsIgnoreCase(stringifyDateString) : true;
     String requestBodyTransformString = GlobalSettings.getProperty("requestBodyTransform");
     requestBodyTransform = requestBodyTransformString != null ? requestBodyTransformString : "";
+    String useDynamicEnumTypeString = GlobalSettings.getProperty("useDynamicEnumType");
+    useDynamicEnumType = useDynamicEnumTypeString != null ? !"false".equalsIgnoreCase(useDynamicEnumTypeString) : false;
+    String overrideDiscriminatorTypeWithValueString = GlobalSettings.getProperty("overrideDiscriminatorTypeWithValue");
+    overrideDiscriminatorTypeWithValue = overrideDiscriminatorTypeWithValueString != null ? !"false".equalsIgnoreCase(overrideDiscriminatorTypeWithValueString) : false;
+    String childrenModelListTypeSuffixString = GlobalSettings.getProperty("childrenModelListTypeSuffix");
+    childrenModelListTypeSuffix = childrenModelListTypeSuffixString;
     typeMapping.put("DateTime", useLegacyDateExtension ? "utils.DateTime" : getDateTimeStandardTime(stringifyDate));
     typeMapping.put("Date", useLegacyDateExtension ? "utils.Date" : getDateType(stringifyDate));
     //TODO binary should be mapped to byte array
@@ -657,6 +666,15 @@ public ModelsMap postProcessModels(ModelsMap objs) {
     // Set additional properties and check non model objects
     for (ModelMap modelMap : models) {
       CodegenModel model = modelMap.getModel();
+
+      if (model.discriminator != null) {
+        List<String> discriminatorValues = new ArrayList<String>();
+        for (CodegenDiscriminator.MappedModel mm : model.discriminator.getMappedModels()) {
+          discriminatorValues.add(mm.getModelName());
+        }
+        model.vendorExtensions.put("x-discriminator-mapping-values", discriminatorValues);
+      }
+
       if (model.isEnum) {
         nonObjectModels.add(toModelName(model.name));
       }
@@ -744,6 +762,9 @@ private ModelsMap postProcessImports(ModelsMap objs) {
   @Override
   public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs) {
     System.out.println("Non object models: " + nonObjectModels.toString());
+
+    Map<String, String> discriminatorField = new HashMap<>();
+    Map<String, String> discriminatorValue = new HashMap<>();
     for (Map.Entry<String, ModelsMap> entry : objs.entrySet()) {
       ModelsMap modelsMap = entry.getValue();
       List<ModelMap> modelMaps = modelsMap.getModels();
@@ -769,12 +790,43 @@ public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs)
             prop.vendorExtensions.put("nonObjectDefinition", nonObjectDefinition);
           }
         }
+
+        if (model.discriminator != null) {
+          for (CodegenDiscriminator.MappedModel mm : model.discriminator.getMappedModels()) {
+            discriminatorField.put(mm.getModelName(), model.discriminator.getPropertyName());
+            discriminatorValue.put(mm.getModelName(), mm.getMappingName());
+          }
+        }
       }
     }
+
     objs = super.postProcessAllModels(objs);
     for (Map.Entry<String, ModelsMap> entry : objs.entrySet()) {
       entry.setValue(this.postProcessImports(entry.getValue()));
+      ModelsMap modelsMap = entry.getValue();
+      List<ModelMap> modelMaps = modelsMap.getModels();
+      for (ModelMap _modelMap : modelMaps) {
+        CodegenModel model = _modelMap.getModel();
+        // Set the useDynamicEnumType vendor extension for the model and its properties to be able to use it in the templates
+        model.vendorExtensions.put("x-use-dynamic-enum-type", useDynamicEnumType);
+        // Set the overrideDiscriminatorTypeWithValue vendor extension for the model to be able to use it in the templates
+        model.vendorExtensions.put("x-override-discriminator-type-with-value", overrideDiscriminatorTypeWithValue);
+        // Set the childrenModelListTypeSuffix vendor extension for the model to be able to use it in the templates
+        model.vendorExtensions.put("x-children-model-list-type-suffix", childrenModelListTypeSuffix);
+        for (CodegenProperty prop : model.getAllVars()) {
+          if (prop.isEnum) {
+            prop.vendorExtensions.put("x-use-dynamic-enum-type", useDynamicEnumType);
+          }
+        }
+
+        // Set discriminator field and value as vendor extension for the model if any, to be able to use it in the templates
+        if (discriminatorField.containsKey(model.classname) && discriminatorValue.containsKey(model.classname)) {
+          model.vendorExtensions.put("x-discriminator-field", discriminatorField.get(model.classname));
+          model.vendorExtensions.put("x-discriminator-value", discriminatorValue.get(model.classname));
+        }
+      }
     }
+
     // if allowModelExtension is true, we don't need to analyze the conditions since we want to ensure the generation of the revivers
     if (!allowModelExtension) {
       Predicate<CodegenProperty> varRequiredReviverPredicate = var -> !(var.isPrimitiveType || var.complexType != null || var.isEnum || var.isEnumRef);

packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/resources/typescriptFetch/api/api.mustache

@@ -1,8 +1,8 @@
 {{#noUnusedImport}}
 {{#imports}}
-import { {{import}} } from '../../models/base/{{#kebabCase}}{{import}}{{/kebabCase}}/index';
+import type { {{import}} } from '../../models/base/{{#kebabCase}}{{import}}{{/kebabCase}}/index';
 {{#keepRevivers}}
-import { revive{{import}} } from '../../models/base/{{#kebabCase}}{{import}}{{/kebabCase}}/{{#kebabCase}}{{import}}{{/kebabCase}}.reviver';
+import type { revive{{import}} } from '../../models/base/{{#kebabCase}}{{import}}{{/kebabCase}}/{{#kebabCase}}{{import}}{{/kebabCase}}.reviver';
 {{/keepRevivers}}
 {{/imports}}
 import { Api, ApiClient, ApiTypes, computePiiParameterTokens, isJsonMimeType, ParamSerializationOptions, RequestBody, RequestMetadata, Server, selectServerBasePath, utils } from '@ama-sdk/core';

packages/@ama-sdk/schematics/schematics/typescript/core/openapi-codegen-typescript/src/main/resources/typescriptFetch/model/model.mustache

@@ -15,7 +15,7 @@ import {utils} from '@ama-sdk/core';
 {{/models}}
 
 {{#imports}}
-import { {{import}} } from '../{{#kebabCase}}{{import}}{{/kebabCase}}';
+import type { {{import}} } from '../{{#kebabCase}}{{import}}{{/kebabCase}}';
 {{/imports}}
 
 {{#models}}
@@ -69,6 +69,10 @@ export interface {{classname}} {{#parent}}extends {{{parent}}} {{/parent}}{
           {{/x-map-name}}
         {{/vendorExtensions}}
       {{/vars}}
+{{#parent}}{{#vendorExtensions}}{{#x-discriminator-field}}{{#x-override-discriminator-type-with-value}}
+  /** @see {{parent}}.{{x-discriminator-field}} */
+  {{x-discriminator-field}}: '{{x-discriminator-value}}';
+{{/x-override-discriminator-type-with-value}}{{/x-discriminator-field}}{{/vendorExtensions}}{{/parent}}
 }
     {{/oneOf}}
     {{#oneOf}}
@@ -84,7 +88,11 @@ export type {{classname}} = {{#oneOf}}{{.}}{{^-last}} | {{/-last}}{{/oneOf}};
 export const {{#upperSnakeCase}}list{{#removeBrackets}}{{{datatypeWithEnum}}}{{/removeBrackets}}{{/upperSnakeCase}} = [{{#trimComma}}{{#vendorExtensions}}{{#x-sanitized-allowable-values}}'{{.}}'{{^-last}}, {{/-last}}{{/x-sanitized-allowable-values}}{{/vendorExtensions}}{{/trimComma}}] as const;
 
 /** List of available values for {{#removeBrackets}}{{{datatypeWithEnum}}}{{/removeBrackets}} */
+{{#vendorExtensions}}{{#x-use-dynamic-enum-type}}
+export type {{#removeBrackets}}{{{datatypeWithEnum}}}{{/removeBrackets}} = typeof {{#upperSnakeCase}}list{{#removeBrackets}}{{{datatypeWithEnum}}}{{/removeBrackets}}{{/upperSnakeCase}}[number];
+{{/x-use-dynamic-enum-type}}{{^x-use-dynamic-enum-type}}
 export type {{#removeBrackets}}{{{datatypeWithEnum}}}{{/removeBrackets}} = {{#trimPipe}}{{#allowableValues}}{{#values}}'{{.}}' | {{/values}}{{/allowableValues}}{{/trimPipe}};
+{{/x-use-dynamic-enum-type}}{{/vendorExtensions}}
         {{/isEnum}}
       {{/allVars}}
     {{/hasEnums}}
@@ -97,12 +105,33 @@ export const {{baseName}}Pattern = {{#parseRegexp}}{{{pattern}}}{{/parseRegexp}}
     {{/vars}}
   {{/isEnum}}
   {{#isEnum}}
-/** Array of {{classname}} items */
-export const {{#upperSnakeCase}}list{{classname}}{{/upperSnakeCase}} = [{{#trimComma}}{{#allowableValues}}{{#values}}'{{.}}'{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}{{/trimComma}}] as const;
+/** @inheritDoc */
+export const {{#upperSnakeCase}}list{{classname}}{{/upperSnakeCase}} = [{{#trimComma}}{{#allowableValues}}{{#values}}'{{.}}'{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}{{/trimComma}}] as const satisfies {{classname}}[];
 
 /** List of available values for {{classname}} */
-export type {{classname}} = {{#trimPipe}}{{#allowableValues}}{{#values}}'{{.}}' | {{/values}}{{/allowableValues}}{{/trimPipe}};
+{{#vendorExtensions}}{{#x-use-dynamic-enum-type}}
+export type {{classname}} = typeof {{#upperSnakeCase}}list{{classname}}{{/upperSnakeCase}}[number];
+{{/x-use-dynamic-enum-type}}{{^x-use-dynamic-enum-type}}
+export type {{classname}} = {{#trimPipe}}{{#allowableValues}}{{#values}}'{{.}}'{{^-last}} | {{/-last}}{{/values}}{{/allowableValues}}{{/trimPipe}};
+{{/x-use-dynamic-enum-type}}{{/vendorExtensions}}
   {{/isEnum}}
+
+{{#vendorExtensions}}{{#discriminator}}{{#x-children-model-list-type-suffix}}
+/** Mapping between discriminator values and their corresponding types for {{classname}} */
+export type {{classname}}{{x-children-model-list-type-suffix}} = {{#x-discriminator-mapping-values}}{{.}}{{^-last}} | {{/-last}}{{/x-discriminator-mapping-values}};
+{{/x-children-model-list-type-suffix}}{{/discriminator}}{{/vendorExtensions}}
+
+{{#parent}}{{#vendorExtensions}}{{#x-discriminator-field}}
+/**
+ * Type guard for {{classname}} implementing the discriminator logic
+ * @param data The data to check
+ * @returns True if the data is of type {{classname}}, false otherwise
+ */
+export const is{{classname}} = (data: {{parent}}): data is {{classname}} => {
+  return (data as any)['{{x-discriminator-field}}'] === '{{x-discriminator-value}}';
+};
+{{/x-discriminator-field}}{{/vendorExtensions}}{{/parent}}
+
 {{/model}}
 {{/models}}
 {{/noUnusedImport}}

packages/@ama-sdk/schematics/schematics/typescript/shell/templates/base/openapitools.json.template

@@ -6,6 +6,7 @@
     "storageDir": ".openapi-generator",
     "generators": {
       "<%=projectName%>-<%=projectPackageName%>": {
+        "useDynamicEnumType": true,
         "generatorName": "typescriptFetch",
         "output": ".",
         "inputSpec": ""

packages/@ama-styling/figma-extractor/package.json

@@ -22,7 +22,7 @@
   "bin": "./cli/figma-extract.js",
   "generatorDependencies": {
     "@ama-styling/style-dictionary": "workspace:~",
-    "style-dictionary": "~5.3.0"
+    "style-dictionary": "~5.4.0"
   },
   "peerDependencies": {
     "@ama-sdk/client-fetch": "workspace:~",

packages/@o3r-training/showcase-sdk/open-api.yaml

@@ -41,6 +41,20 @@ tags:
   - name: user
     description: Operations about user
 paths:
+  /animal:
+    get:
+      tags:
+        - "dummy"
+      summary: Animal get
+      description: Get an animal
+      operationId: animalGet
+      responses:
+        200:
+          description: "Successful operation"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Animal'
   /pet:
     post:
       servers:
@@ -630,6 +644,38 @@ externalDocs:
   url: 'http://swagger.io'
 components:
   schemas:
+    Animal:
+      type: object
+      required:
+        - petType
+      properties:
+        petType:
+          type: string
+          enum: [cat, dog] # <- optional enum, can be forgotten in the declaration without changing generated code
+      discriminator:
+        propertyName: petType
+        mapping: # <- mandatory
+          dog: "#/components/schemas/Dog"
+          cat: "#/components/schemas/Cat"
+    Dog:
+      allOf:
+        - $ref: '#/components/schemas/Animal'
+        - type: object
+          properties:
+            bark:
+              type: boolean
+            breed:
+              type: string
+              enum: [Dingo, Husky, Retriever, Shepherd]
+    Cat:
+      allOf:
+        - $ref: '#/components/schemas/Animal'
+        - type: object
+          properties:
+            hunts:
+              type: boolean
+            age:
+              type: integer
     Order:
       x-swagger-router-model: io.swagger.petstore.model.Order
       properties:

packages/@o3r-training/showcase-sdk/openapitools.json

@@ -10,7 +10,10 @@
         "output": ".",
         "inputSpec": "./open-api.yaml",
         "globalProperty": {
+          "overrideDiscriminatorTypeWithValue": true,
+          "useDynamicEnumType": true,
           "stringifyDate": true,
+          "childrenModelListTypeSuffix": "Children",
           "requestBodyTransform": "content{{bodyRequest}}"
         }
       }