Add support for x-enumNames and x-enumDescriptions enum names (#1416)

* Updated advanced.md to include x-enumNames and x-enumDescriptions

* Update schema-object.ts to include x-enumNames and x-enumDescriptions

* Prettify

* Added link to NSwag/NJsonSchema

* Added tesst for x-enum-varnames with x-enum-descriptions and x-enumNames with x-enumDescriptions.

* Format

---------

Co-authored-by: Drew Powers <[email protected]>

Author: alex-aveva

docs/6.x/advanced.md

@@ -189,6 +189,49 @@ export function mockResponses(responses: {
 
 Now, whenever your schema updates, **all your mock data will be typechecked correctly** 🎉. This is a huge step in ensuring resilient, accurate tests.
 
+## Enum extensions
+
+`x-enum-varnames` can be used to have another enum name for the corresponding value. This is used to define names of the enum items.
+
+`x-enum-descriptions` can be used to provide an individual description for each value. This is used for comments in the code (like javadoc if the target language is java).
+
+`x-enum-descriptions` and `x-enum-varnames` are each expected to be list of items containing the same number of items as enum. The order of the items in the list matters: their position is used to group them together.
+
+Example:
+
+```yaml
+ErrorCode:
+  type: integer
+  format: int32
+  enum:
+    - 100
+    - 200
+    - 300
+  x-enum-varnames:
+    - Unauthorized
+    - AccessDenied
+    - Unknown
+  x-enum-descriptions:
+    - "User is not authorized"
+    - "User has no access to this resource"
+    - "Something went wrong"
+```
+
+Will result in:
+
+```ts
+enum ErrorCode {
+  // User is not authorized
+  Unauthorized = 100
+  // User has no access to this resource
+  AccessDenied = 200
+  // Something went wrong
+  Unknown = 300
+}
+```
+
+Alternatively you can use `x-enumNames` and `x-enumDescriptions` ([NSwag/NJsonSchema](https://github.com/RicoSuter/NJsonSchema/wiki/Enums#enum-names-and-descriptions)).
+
 ## Tips
 
 In no particular order, here are a few best practices to make life easier when working with OpenAPI-derived types.

docs/advanced.md

@@ -19,8 +19,6 @@ To only see certain types of debug messages, you can set `DEBUG=openapi-ts:[scop
 
 Note that debug messages will be suppressed if the output is `stdout`.
 
-In no particular order, here are a few best practices to make life easier when working with OpenAPI-derived types.
-
 ## Enum extensions
 
 `x-enum-varnames` can be used to have another enum name for the corresponding value. This is used to define names of the enum items.
@@ -62,6 +60,8 @@ enum ErrorCode {
 }
 ```
 
+Alternatively you can use `x-enumNames` and `x-enumDescriptions` ([NSwag/NJsonSchema](https://github.com/RicoSuter/NJsonSchema/wiki/Enums#enum-names-and-descriptions)).
+
 ## Styleguide
 
 Loose recommendations to improve type generation.

packages/openapi-typescript/src/transform/schema-object.ts

@@ -115,8 +115,12 @@ export function transformSchemaObjectWithComposition(
       // allow #/components/schemas to have simpler names
       enumName = enumName.replace("components/schemas", "");
       const metadata = schemaObject.enum.map((_, i) => ({
-        name: schemaObject["x-enum-varnames"]?.[i],
-        description: schemaObject["x-enum-descriptions"]?.[i],
+        name:
+          schemaObject["x-enum-varnames"]?.[i] ??
+          schemaObject["x-enumNames"]?.[i],
+        description:
+          schemaObject["x-enum-descriptions"]?.[i] ??
+          schemaObject["x-enumDescriptions"]?.[i],
       }));
       const enumType = tsEnum(
         enumName,

packages/openapi-typescript/test/node-api.test.ts

@@ -509,6 +509,26 @@ export type operations = Record<string, never>;`,
                 type: "number",
                 enum: [100, 101, 102, 103, 104, 105],
               },
+              XEnumVarnames: {
+                type: "number",
+                enum: [0, 1, 2],
+                "x-enum-varnames": ["Success", "Warning", "Error"],
+                "x-enum-descriptions": [
+                  "Used when the status of something is successful",
+                  "Used when the status of something has a warning",
+                  "Used when the status of something has an error",
+                ],
+              },
+              XEnumNames: {
+                type: "number",
+                enum: [1, 2, 3],
+                "x-enumNames": ["Uno", "Dos", "Tres"],
+                "x-enumDescriptions": [
+                  "El número uno",
+                  "El número dos",
+                  "El número tres",
+                ],
+              },
             },
           },
         },
@@ -548,6 +568,10 @@ export interface components {
         Status: Status;
         /** @enum {number} */
         ErrorCode: ErrorCode;
+        /** @enum {number} */
+        XEnumVarnames: XEnumVarnames;
+        /** @enum {number} */
+        XEnumNames: XEnumNames;
     };
     responses: never;
     parameters: never;
@@ -572,6 +596,22 @@ export enum ErrorCode {
     Value104 = 104,
     Value105 = 105
 }
+export enum XEnumVarnames {
+    // Used when the status of something is successful
+    Success = 0,
+    // Used when the status of something has a warning
+    Warning = 1,
+    // Used when the status of something has an error
+    Error = 2
+}
+export enum XEnumNames {
+    // El número uno
+    Uno = 1,
+    // El número dos
+    Dos = 2,
+    // El número tres
+    Tres = 3
+}
 export type operations = Record<string, never>;`,
         options: { enum: true },
       },