docs(api-sdk): enums specific properties use-case

Author: vscaiceanu-1a

.github/ISSUE_TEMPLATE/2-AMA-SDK-ISSUE-FORM.yaml

@@ -17,7 +17,7 @@ body:
         core,
         create,
         schematics,
-        showcase-sdk
+        showcase-sdk,
         swagger-builder
       ]
     validations:

docs/api-sdk/COMPOSITION_INHERITANCE.md

@@ -62,7 +62,7 @@ export interface ExtendedErrorModel {
 
 The addition of a discriminator allows a hierarchy between the models and the possibility to identify which child class
 a model can be casted into.
-For example, let's consider a Pet object and its two class child Cat and Dog:
+For example, let's consider a Pet object and its two child classes Cat and Dog:
 
 ```yaml
 components:

docs/api-sdk/ISSUES_AND_WORKAROUNDS.md

@@ -0,0 +1,41 @@
+# Issues and workarounds
+
+## `properties` for `allOf` instruction
+
+Currently, using `properties` for the `allOf` instruction is not supported by the SDK generator. For instance, it can incorrectly handle `enum` generation.
+
+```yaml
+Dog:
+  allOf:
+    - $ref: '#/components/schemas/Pet'
+  properties:
+    bark:
+      type: boolean
+    breed:
+      type: string
+      enum: [Dingo, Husky, Retriever, Shepherd]
+```
+
+It will not generate the `breed` enum.
+
+As a workaround, you can pass the properties as an object to the `allOf` array as follows:
+
+```yaml
+Dog:
+  allOf:
+    - $ref: '#/components/schemas/Pet'
+    - type: object
+      properties:
+        bark:
+          type: boolean
+        breed:
+          type: string
+          enum: [Dingo, Husky, Retriever, Shepherd]
+```
+
+This will generate:
+```typescript
+export type BreedEnum = 'Dingo' | 'Husky' | 'Retriever' | 'Sheperd';
+```
+
+The issue is tracked via https://github.com/AmadeusITGroup/otter/issues/2832.