Add support for x-enum-varnames and x-enum-descriptions

Author: ElForastero

.changeset/chilled-news-design.md

@@ -0,0 +1,5 @@
+---
+"openapi-typescript": major
+---
+
+Add support for x-enum-varnames and x-enum-descriptions

packages/openapi-typescript/src/lib/ts.ts

@@ -229,6 +229,8 @@ export function tsDedupe(types: ts.TypeNode[]): ts.TypeNode[] {
 export function tsEnum(
   name: string,
   members: (string | number)[],
+  membersNames?: string[],
+  membersDescriptions?: string[],
   options?: { readonly?: boolean; export?: boolean },
 ) {
   let enumName = name.replace(JS_ENUM_INVALID_CHARS_RE, (c) => {
@@ -249,28 +251,48 @@ export function tsEnum(
         })
       : undefined,
     /* name      */ enumName,
-    /* members   */ members.map(tsEnumMember),
+    /* members   */ members.map((value, i) =>
+      tsEnumMember(value, membersNames?.[i], membersDescriptions?.[i]),
+    ),
   );
 }
 
 /** Sanitize TS enum member expression */
-export function tsEnumMember(value: string | number) {
-  if (typeof value === "number") {
-    return ts.factory.createEnumMember(
-      `Value${String(value)}`.replace(".", "_"), // don’t forget decimals
-      ts.factory.createNumericLiteral(value),
-    );
-  }
-  let name = value;
+export function tsEnumMember(
+  value: string | number,
+  memberName?: string,
+  description?: string,
+) {
+  let name = memberName ?? String(value);
   if (!JS_PROPERTY_INDEX_RE.test(name)) {
     if (Number(name[0]) >= 0) {
-      name = `Value${name}`;
+      name = `Value${name}`.replace(".", "_"); // don't forged decimals;
     }
     name = name.replace(JS_PROPERTY_INDEX_INVALID_CHARS_RE, "_");
   }
-  return ts.factory.createEnumMember(
-    name,
-    ts.factory.createStringLiteral(value),
+
+  let member;
+  if (typeof value === "number") {
+    member = ts.factory.createEnumMember(
+      name,
+      ts.factory.createNumericLiteral(value),
+    );
+  } else {
+    member = ts.factory.createEnumMember(
+      name,
+      ts.factory.createStringLiteral(value),
+    );
+  }
+
+  if (description == undefined) {
+    return member;
+  }
+
+  return ts.addSyntheticLeadingComment(
+    member,
+    ts.SyntaxKind.SingleLineCommentTrivia,
+    " ".concat(description.trim()),
+    true,
   );
 }
 

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

@@ -127,6 +127,8 @@ export function transformSchemaObjectWithComposition(
       const enumType = tsEnum(
         enumName,
         schemaObject.enum as (string | number)[],
+        schemaObject["x-enum-varnames"],
+        schemaObject["x-enum-descriptions"],
         { export: true, readonly: options.ctx.immutable },
       );
       options.ctx.injectFooter.push(enumType);

packages/openapi-typescript/test/lib/ts.test.ts

@@ -127,6 +127,77 @@ describe("tsEnum", () => {
     Value100 = 100,
     Value101 = 101,
     Value102 = 102
+}`);
+  });
+
+  it("number members with x-enum-descriptions", () => {
+    expect(
+      astToString(
+        tsEnum(".Error.code.", [100, 101, 102], undefined, [
+          "Code 100",
+          "Code 101",
+          "Code 102",
+        ]),
+      ).trim(),
+    ).toBe(`enum ErrorCode {
+    // Code 100
+    Value100 = 100,
+    // Code 101
+    Value101 = 101,
+    // Code 102
+    Value102 = 102
+}`);
+  });
+
+  it("x-enum-varnames", () => {
+    expect(
+      astToString(
+        tsEnum(
+          ".Error.code.",
+          [100, 101, 102],
+          ["Unauthorized", "NotFound", "PermissionDenied"],
+        ),
+      ).trim(),
+    ).toBe(`enum ErrorCode {
+    Unauthorized = 100,
+    NotFound = 101,
+    PermissionDenied = 102
+}`);
+  });
+
+  it("x-enum-varnames with numeric prefix", () => {
+    expect(
+      astToString(
+        tsEnum(".Error.code.", [100, 101, 102], ["0a", "1b", "2c"]),
+      ).trim(),
+    ).toBe(`enum ErrorCode {
+    Value0a = 100,
+    Value1b = 101,
+    Value2c = 102
+}`);
+  });
+
+  it("x-enum-descriptions with x-enum-varnames", () => {
+    expect(
+      astToString(
+        tsEnum(
+          ".Error.code.",
+          [100, 101, 102],
+          ["Unauthorized", "NotFound", "PermissionDenied"],
+          [
+            "User is unauthorized",
+            "Item not found",
+            "User doesn't have permissions",
+          ],
+        ),
+      ).trim(),
+    ).toBe(`enum ErrorCode {
+    // User is unauthorized
+    Unauthorized = 100,
+    // Item not found
+    NotFound = 101,
+    // User doesn't have permissions
+    PermissionDenied = 102
 }`);
   });
 });