feat: add support x-enum-descriptions (#1299)

* feat: add support x-enum-descriptions

* chore: fix format PR

Author: js2me

.changeset/wild-badgers-retire.md

@@ -0,0 +1,5 @@
+---
+"swagger-typescript-api": patch
+---
+
+added support of x-enum-descriptions property

src/configuration.ts

@@ -289,13 +289,33 @@ export class CodeGenConfig {
      */
     EnumField: (key: unknown, value: unknown) => `${key} = ${value}`,
     /**
+     * /\** description \*\/
+     */
+    EnumFieldDescription: (description: any) => {
+      if (description) {
+        return `  /** ${description} */`;
+      } else {
+        return "";
+      }
+    },
+    /**
+     * /\** $A0.description \*\/
      * $A0.key = $A0.value,
+     * /\** $A1.description \*\/
      * $A1.key = $A1.value,
+     * /\** $AN.description \*\/
      * $AN.key = $AN.value,
      */
     EnumFieldsWrapper: (contents: Record<string, unknown>[]) =>
       lodash
-        .map(contents, ({ key, value }) => `  ${this.Ts.EnumField(key, value)}`)
+        .map(contents, ({ key, value, description }) => {
+          return [
+            this.Ts.EnumFieldDescription(description),
+            `  ${this.Ts.EnumField(key, value)}`,
+          ]
+            .filter(Boolean)
+            .join("\n");
+        })
         .join(",\n"),
     /**
      * {\n $A \n}

src/schema-parser/base-schema-parsers/enum.ts

@@ -63,6 +63,8 @@ export class EnumSchemaParser extends MonoSchemaParser {
 
     const keyType = this.schemaUtils.getSchemaType(this.schema);
     const enumNames = this.schemaUtils.getEnumNames(this.schema);
+    const enumDescriptions = this.schemaUtils.getEnumDescriptions(this.schema);
+
     let content = null;
 
     const formatValue = (value) => {
@@ -96,22 +98,25 @@ export class EnumSchemaParser extends MonoSchemaParser {
             key: formattedKey,
             type: this.config.Ts.Keyword.String,
             value: this.config.Ts.StringValue(enumName),
+            description: enumDescriptions?.[index],
           };
         }
 
         return {
           key: formattedKey,
           type: keyType,
           value: formatValue(enumValue),
+          description: enumDescriptions?.[index],
         };
       });
     } else {
-      content = this.schema.enum.map((value) => {
+      content = this.schema.enum.map((value, index) => {
         return {
           // @ts-expect-error TS(2345) FIXME: Argument of type '{ value: any; }' is not assignab... Remove this comment to see the full error message
           key: this.formatEnumKey({ value }),
           type: keyType,
           value: formatValue(value),
+          description: enumDescriptions?.[index],
         };
       });
     }

src/schema-parser/schema-utils.ts

@@ -44,6 +44,15 @@ export class SchemaUtils {
     );
   };
 
+  getEnumDescriptions = (schema) => {
+    return (
+      schema["x-enumDescriptions"] ||
+      schema.xEnumDescriptions ||
+      schema["x-enumdescriptions"] ||
+      schema["x-enum-descriptions"]
+    );
+  };
+
   getSchemaRefType = (schema) => {
     if (!this.isRefSchema(schema)) return null;
     return this.schemaComponentsMap.get(schema.$ref);

templates/base/enum-data-contract.ejs

@@ -7,6 +7,12 @@ const { name, $content } = contract;
   export type <%~ name %> = <%~ _.map($content, ({ value }) => value).join(" | ") %>
 <% } else { %>
   export enum <%~ name %> {
-    <%~ _.map($content, ({ key, value }) => `${key} = ${value}`).join(",\n") %>
+    <%~ _.map($content, ({ key, value, description }) => {
+      let formattedDescription = description && formatDescription(description, true);
+      return [
+        formattedDescription && `/** ${formattedDescription} */`,
+        `${key} = ${value}`
+      ].filter(Boolean).join("\n");
+    }).join(",\n") %>
   }
 <% } %>

tests/spec/enumIncludesNumber/__snapshots__/basic.test.ts.snap

@@ -14,8 +14,11 @@ exports[`basic > use x-enumNames as the key for enum 1`] = `
  */
 
 export enum StringEnumIncludesNumbersAndUnderscore {
+  /** Foo */
   VAL_1 = "VAL_1",
+  /** Bar */
   VAL_2 = "VAL_2",
+  /** Baz */
   VAL_3 = "VAL_3",
   _1_VAL = "_1_VAL",
   A_1_B_2_C_3 = "A_1_B_2_C_3",

tests/spec/enumIncludesNumber/schema.json

@@ -14,7 +14,8 @@
           "A_1_B_2_C_3",
           "_A_1_B_2_C_3",
           "_1_A_2_B_3_C"
-        ]
+        ],
+        "x-enum-descriptions": ["Foo", "Bar", "Baz"]
       }
     }
   }