feat: add support for individual enum variant descriptions

Author: koralkulacoglu

packages/openapi-generator/src/knownImports.ts

@@ -125,10 +125,16 @@ export const KNOWN_IMPORTS: KnownImports = {
       if (arg.type !== 'object') {
         return errorLeft(`Unimplemented keyof type ${arg.type}`);
       }
-      const schemas: Schema[] = Object.keys(arg.properties).map((prop) => ({
-        type: 'string',
-        enum: [prop],
-      }));
+      const schemas: Schema[] = Object.keys(arg.properties).map((prop) => {
+        const propertySchema = arg.properties[prop];
+        return {
+          type: 'string',
+          enum: [prop],
+          // Preserve the comment from the original property
+          ...(propertySchema?.comment ? { comment: propertySchema.comment } : {}),
+        };
+      });
+
       return E.right({
         type: 'union',
         schemas,

packages/openapi-generator/src/optimize.ts

@@ -160,9 +160,14 @@ export function simplifyUnion(schema: Schema, optimize: OptimizeFn): Schema {
   const remainder: Schema[] = [];
   innerSchemas.forEach((innerSchema) => {
     if (isPrimitive(innerSchema) && innerSchema.enum !== undefined) {
-      innerSchema.enum.forEach((value) => {
-        literals[innerSchema.type].add(value);
-      });
+      // If this enum has a comment, preserve it in the union instead of consolidating
+      if (innerSchema.comment) {
+        remainder.push(innerSchema);
+      } else {
+        innerSchema.enum.forEach((value) => {
+          literals[innerSchema.type].add(value);
+        });
+      }
     } else {
       remainder.push(innerSchema);
     }

packages/openapi-generator/test/openapi/comments.test.ts

@@ -1441,6 +1441,180 @@ testCase(
   },
 );
 
+const ROUTE_WITH_INDIVIDUAL_ENUM_DESCRIPTIONS = `
+import * as t from 'io-ts';
+import * as h from '@api-ts/io-ts-http';
+
+/**
+ * Transaction Request State Enum with individual descriptions
+ */
+export const TransactionRequestState = t.keyof(
+  {
+    /** Transaction is waiting for approval from authorized users */
+    pendingApproval: 1,
+    /** Transaction was canceled by the user */
+    canceled: 1,
+    /** Transaction was rejected by approvers */
+    rejected: 1,
+    /** Transaction has been initialized but not yet processed */
+    initialized: 1,
+    /** Transaction is ready to be delivered */
+    pendingDelivery: 1,
+    /** Transaction has been successfully delivered */
+    delivered: 1,
+  },
+  'TransactionRequestState',
+);
+
+/**
+ * Route to test individual enum variant descriptions
+ *
+ * @operationId api.v1.enumVariantDescriptions
+ * @tag Test Routes
+ */
+export const route = h.httpRoute({
+  path: '/transactions',
+  method: 'GET',
+  request: h.httpRequest({
+    query: {
+      states: t.array(TransactionRequestState),
+    },
+  }),
+  response: {
+    200: {
+      result: t.string
+    }
+  },
+});
+`;
+
+testCase(
+  'individual enum variant descriptions are preserved in oneOf',
+  ROUTE_WITH_INDIVIDUAL_ENUM_DESCRIPTIONS,
+  {
+    openapi: '3.0.3',
+    info: {
+      title: 'Test',
+      version: '1.0.0',
+    },
+    paths: {
+      '/transactions': {
+        get: {
+          summary: 'Route to test individual enum variant descriptions',
+          operationId: 'api.v1.enumVariantDescriptions',
+          tags: ['Test Routes'],
+          parameters: [
+            {
+              name: 'states',
+              description:
+                'Transaction Request State Enum with individual descriptions',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'array',
+                items: {
+                  oneOf: [
+                    {
+                      type: 'string',
+                      enum: ['pendingApproval'],
+                      description:
+                        'Transaction is waiting for approval from authorized users',
+                    },
+                    {
+                      type: 'string',
+                      enum: ['canceled'],
+                      description: 'Transaction was canceled by the user',
+                    },
+                    {
+                      type: 'string',
+                      enum: ['rejected'],
+                      description: 'Transaction was rejected by approvers',
+                    },
+                    {
+                      type: 'string',
+                      enum: ['initialized'],
+                      description:
+                        'Transaction has been initialized but not yet processed',
+                    },
+                    {
+                      type: 'string',
+                      enum: ['pendingDelivery'],
+                      description: 'Transaction is ready to be delivered',
+                    },
+                    {
+                      type: 'string',
+                      enum: ['delivered'],
+                      description: 'Transaction has been successfully delivered',
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+          responses: {
+            200: {
+              description: 'OK',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      result: {
+                        type: 'string',
+                      },
+                    },
+                    required: ['result'],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        TransactionRequestState: {
+          title: 'TransactionRequestState',
+          description: 'Transaction Request State Enum with individual descriptions',
+          oneOf: [
+            {
+              type: 'string',
+              enum: ['pendingApproval'],
+              description: 'Transaction is waiting for approval from authorized users',
+            },
+            {
+              type: 'string',
+              enum: ['canceled'],
+              description: 'Transaction was canceled by the user',
+            },
+            {
+              type: 'string',
+              enum: ['rejected'],
+              description: 'Transaction was rejected by approvers',
+            },
+            {
+              type: 'string',
+              enum: ['initialized'],
+              description: 'Transaction has been initialized but not yet processed',
+            },
+            {
+              type: 'string',
+              enum: ['pendingDelivery'],
+              description: 'Transaction is ready to be delivered',
+            },
+            {
+              type: 'string',
+              enum: ['delivered'],
+              description: 'Transaction has been successfully delivered',
+            },
+          ],
+        },
+      },
+    },
+  },
+);
+
 const ROUTE_WITH_ENUM_ARRAY_PARAMETER_DESCRIPTIONS = `
 import * as t from 'io-ts';
 import * as h from '@api-ts/io-ts-http';