Refactor ts enum members

Author: ElForastero

.changeset/chilled-news-design.md

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

docs/src/content/docs/advanced.md

@@ -521,3 +521,44 @@ Cat: { type?: "cat"; } & components["schemas"]["PetCommonProperties"];
 _Note: you optionally could provide `discriminator.propertyName: "type"` on `Pet` ([docs](https://spec.openapis.org/oas/v3.1.0#discriminator-object)) to automatically generate the `type` key, but is less explicit._
 
 While the schema permits you to use composition in any way you like, it’s good to always take a look at the generated types and see if there’s a simpler way to express your unions & intersections. Limiting the use of `oneOf` is not the only way to do that, but often yields the greatest benefits.
+
+### Enum with custom names and descriptions
+
+`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
+}
+```

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

@@ -229,8 +229,7 @@ export function tsDedupe(types: ts.TypeNode[]): ts.TypeNode[] {
 export function tsEnum(
   name: string,
   members: (string | number)[],
-  membersNames?: string[],
-  membersDescriptions?: string[],
+  metadata?: { name?: string; description?: string }[],
   options?: { readonly?: boolean; export?: boolean },
 ) {
   let enumName = name.replace(JS_ENUM_INVALID_CHARS_RE, (c) => {
@@ -252,18 +251,17 @@ export function tsEnum(
       : undefined,
     /* name      */ enumName,
     /* members   */ members.map((value, i) =>
-      tsEnumMember(value, membersNames?.[i], membersDescriptions?.[i]),
+      tsEnumMember(value, metadata?.[i]),
     ),
   );
 }
 
 /** Sanitize TS enum member expression */
 export function tsEnumMember(
   value: string | number,
-  memberName?: string,
-  description?: string,
+  metadata: { name?: string; description?: string } = {},
 ) {
-  let name = memberName ?? String(value);
+  let name = metadata.name ?? String(value);
   if (!JS_PROPERTY_INDEX_RE.test(name)) {
     if (Number(name[0]) >= 0) {
       name = `Value${name}`.replace(".", "_"); // don't forged decimals;
@@ -284,14 +282,14 @@ export function tsEnumMember(
     );
   }
 
-  if (description == undefined) {
+  if (metadata.description == undefined) {
     return member;
   }
 
   return ts.addSyntheticLeadingComment(
     member,
     ts.SyntaxKind.SingleLineCommentTrivia,
-    " ".concat(description.trim()),
+    " ".concat(metadata.description.trim()),
     true,
   );
 }

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

@@ -124,11 +124,14 @@ export function transformSchemaObjectWithComposition(
       let enumName = parseRef(options.path ?? "").pointer.join("/");
       // 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],
+      }));
       const enumType = tsEnum(
         enumName,
         schemaObject.enum as (string | number)[],
-        schemaObject["x-enum-varnames"],
-        schemaObject["x-enum-descriptions"],
+        metadata,
         { export: true, readonly: options.ctx.immutable },
       );
       options.ctx.injectFooter.push(enumType);

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

@@ -133,11 +133,15 @@ describe("tsEnum", () => {
   it("number members with x-enum-descriptions", () => {
     expect(
       astToString(
-        tsEnum(".Error.code.", [100, 101, 102], undefined, [
-          "Code 100",
-          "Code 101",
-          "Code 102",
-        ]),
+        tsEnum(
+          ".Error.code.",
+          [100, 101, 102],
+          [
+            { description: "Code 100" },
+            { description: "Code 101" },
+            { description: "Code 102" },
+          ],
+        ),
       ).trim(),
     ).toBe(`enum ErrorCode {
     // Code 100
@@ -155,7 +159,11 @@ describe("tsEnum", () => {
         tsEnum(
           ".Error.code.",
           [100, 101, 102],
-          ["Unauthorized", "NotFound", "PermissionDenied"],
+          [
+            { name: "Unauthorized" },
+            { name: "NotFound" },
+            { name: "PermissionDenied" },
+          ],
         ),
       ).trim(),
     ).toBe(`enum ErrorCode {
@@ -168,7 +176,11 @@ describe("tsEnum", () => {
   it("x-enum-varnames with numeric prefix", () => {
     expect(
       astToString(
-        tsEnum(".Error.code.", [100, 101, 102], ["0a", "1b", "2c"]),
+        tsEnum(
+          ".Error.code.",
+          [100, 101, 102],
+          [{ name: "0a" }, { name: "1b" }, { name: "2c" }],
+        ),
       ).trim(),
     ).toBe(`enum ErrorCode {
     Value0a = 100,
@@ -177,17 +189,39 @@ describe("tsEnum", () => {
 }`);
   });
 
+  it("partial x-enum-varnames and x-enum-descriptions", () => {
+    expect(
+      astToString(
+        tsEnum(
+          ".Error.code.",
+          [100, 101, 102],
+          [
+            { name: "Unauthorized", description: "User is unauthorized" },
+            { name: "NotFound" },
+          ],
+        ),
+      ).trim(),
+    ).toBe(`enum ErrorCode {
+    // User is unauthorized
+    Unauthorized = 100,
+    NotFound = 101,
+    Value102 = 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",
+            { name: "Unauthorized", description: "User is unauthorized" },
+            { name: "NotFound", description: "Item not found" },
+            {
+              name: "PermissionDenied",
+              description: "User doesn't have permissions",
+            },
           ],
         ),
       ).trim(),