feat(openapi-resource-gen): emit enum label/description maps from x-enum-varnames / x-enum-descriptions

For each query, path, or header parameter annotated with x-enum-varnames or
x-enum-descriptions vendor extensions, emit a typed as-const object map alongside the
token — e.g. listPetsStatusLabels / listPetsStatusDescriptions. Keys are the raw enum
values; values are the human-readable names or descriptions. Enables dropdown label
generation without hand-maintaining a parallel mapping.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: constantant

tools/openapi-resource-gen/src/generators/api-resource/endpoint-model.ts

@@ -12,6 +12,18 @@ export interface DiscriminatorModel {
   isArrayResponse: boolean;
 }
 
+/** An enum parameter or response property annotated with x-enum-varnames / x-enum-descriptions. */
+export interface EnumExtension {
+  /** Parameter or property name, e.g. 'status'. */
+  paramName: string;
+  /** Raw enum values from the spec, e.g. ['placed', 'approved']. */
+  values: string[];
+  /** Human-readable names from x-enum-varnames, parallel to values. */
+  varnames?: string[];
+  /** Long-form descriptions from x-enum-descriptions, parallel to values. */
+  descriptions?: string[];
+}
+
 /** A response property with format:date-time or format:date. */
 export interface DateField {
   name: string;
@@ -90,6 +102,8 @@ export interface EndpointModel {
   securitySchemeNames: string[];
   /** Present when the primary response schema carries a discriminator. */
   discriminator: DiscriminatorModel | null;
+  /** Enum parameters/properties with x-enum-varnames or x-enum-descriptions vendor extensions. */
+  enumExtensions: EnumExtension[];
   /** Date/datetime fields on the primary response object, for optional reviver generation. */
   dateFields: DateField[];
   /** True when the primary JSON response type is an array. */

tools/openapi-resource-gen/src/generators/api-resource/generator.spec.ts

@@ -1152,6 +1152,119 @@ describe('api-resource generator', () => {
     });
   });
 
+  describe('x-enum-varnames / x-enum-descriptions', () => {
+    const ENUM_SPEC = {
+      paths: {
+        '/pets': {
+          get: {
+            operationId: 'listPets',
+            tags: ['pets'],
+            parameters: [
+              {
+                in: 'query',
+                name: 'status',
+                schema: {
+                  type: 'string',
+                  enum: ['available', 'pending', 'sold'],
+                  'x-enum-varnames': ['Available', 'Pending', 'Sold'],
+                  'x-enum-descriptions': [
+                    'Pet is available',
+                    'Pet is pending sale',
+                    'Pet has been sold',
+                  ],
+                },
+              },
+            ],
+            responses: { '200': { content: { 'application/json': { schema: {} } } } },
+          },
+        },
+      },
+    };
+
+    it('emits a labels map for a param with x-enum-varnames', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(ENUM_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/enum-labels/src',
+      });
+      const content = tree.read('libs/enum-labels/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).toContain('export const listPetsStatusLabels = {');
+      expect(content).toContain("available: 'Available'");
+      expect(content).toContain("pending: 'Pending'");
+      expect(content).toContain("sold: 'Sold'");
+      expect(content).toContain('} as const;');
+    });
+
+    it('emits a descriptions map for a param with x-enum-descriptions', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(ENUM_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/enum-desc/src',
+      });
+      const content = tree.read('libs/enum-desc/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).toContain('export const listPetsStatusDescriptions = {');
+      expect(content).toContain("available: 'Pet is available'");
+      expect(content).toContain("sold: 'Pet has been sold'");
+      expect(content).toContain('} as const;');
+    });
+
+    it('emits both labels and descriptions when both extensions are present', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(ENUM_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/enum-both/src',
+      });
+      const content = tree.read('libs/enum-both/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).toContain('listPetsStatusLabels');
+      expect(content).toContain('listPetsStatusDescriptions');
+    });
+
+    it('handles path params with x-enum-varnames', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/pets/{type}': {
+            get: {
+              operationId: 'getPetByType',
+              tags: ['pets'],
+              parameters: [
+                {
+                  in: 'path',
+                  name: 'type',
+                  required: true,
+                  schema: {
+                    type: 'string',
+                    enum: ['cat', 'dog'],
+                    'x-enum-varnames': ['Cat', 'Dog'],
+                  },
+                },
+              ],
+              responses: { '200': { content: { 'application/json': { schema: {} } } } },
+            },
+          },
+        },
+      } as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/enum-path/src',
+      });
+      const content = tree.read('libs/enum-path/src/pets/get-pet-by-type.token.ts', 'utf-8')!;
+      expect(content).toContain('export const getPetByTypeTypeLabels = {');
+      expect(content).toContain("cat: 'Cat'");
+      expect(content).toContain("dog: 'Dog'");
+    });
+
+    it('does not emit enum maps when no vendor extensions are present', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/enum-none/src',
+      });
+      // MOCK_SPEC has a limit query param but no x-enum-varnames
+      const content = tree.read('libs/enum-none/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).not.toContain('Labels =');
+      expect(content).not.toContain('Descriptions =');
+    });
+  });
+
   describe('readonly response types', () => {
     it('wraps XxxResponse in Readonly<> when readonlyResponses is true', async () => {
       await apiResourceGenerator(tree, {

tools/openapi-resource-gen/src/generators/api-resource/parse-spec.ts

@@ -1,6 +1,6 @@
 import SwaggerParser from '@apidevtools/swagger-parser';
 import { OpenAPIV3 } from 'openapi-types';
-import type { DateField, DiscriminatorModel, DiscriminatorVariant, EndpointModel, SecurityKind, SecuritySchemeModel, SpecialQueryParam, WebhookModel } from './endpoint-model';
+import type { DateField, DiscriminatorModel, DiscriminatorVariant, EndpointModel, EnumExtension, SecurityKind, SecuritySchemeModel, SpecialQueryParam, WebhookModel } from './endpoint-model';
 
 const HTTP_METHODS: ReadonlyArray<OpenAPIV3.HttpMethods> = [
   OpenAPIV3.HttpMethods.GET,
@@ -121,6 +121,29 @@ function collectDateFields(schema: OpenAPIV3.SchemaObject | null | undefined): D
     }));
 }
 
+/** Collect x-enum-varnames / x-enum-descriptions from the query/path/header parameters of an operation. */
+function collectEnumExtensions(params: OpenAPIV3.ParameterObject[]): EnumExtension[] {
+  const result: EnumExtension[] = [];
+  for (const p of params) {
+    const schema = p.schema as (OpenAPIV3.SchemaObject & {
+      'x-enum-varnames'?: string[];
+      'x-enum-descriptions'?: string[];
+    }) | undefined;
+    if (!schema || !Array.isArray(schema.enum)) continue;
+    const varnames = schema['x-enum-varnames'];
+    const descriptions = schema['x-enum-descriptions'];
+    if (!varnames && !descriptions) continue;
+    const values = (schema.enum as unknown[]).map(String);
+    result.push({
+      paramName: p.name,
+      values,
+      ...(varnames ? { varnames: varnames.slice(0, values.length) } : {}),
+      ...(descriptions ? { descriptions: descriptions.slice(0, values.length) } : {}),
+    });
+  }
+  return result;
+}
+
 export function buildEndpoints(
   api: OpenAPIV3.Document,
   allowedTags: string[] | null,
@@ -188,6 +211,8 @@ export function buildEndpoints(
           return [];
         });
 
+      const enumExtensions = collectEnumExtensions(allParams);
+
       // Operation-level security overrides global; [] means explicitly no security.
       const operationSecurity = operation.security as
         | OpenAPIV3.SecurityRequirementObject[]
@@ -277,6 +302,7 @@ export function buildEndpoints(
         securitySchemeNames,
         errorStatuses,
         discriminator,
+        enumExtensions,
         dateFields,
         responseIsArray,
       });

tools/openapi-resource-gen/src/generators/api-resource/render-token.ts

@@ -164,6 +164,25 @@ export function renderTokenFile(
       ''
     );
   }
+
+  // Enum label / description maps from x-enum-varnames / x-enum-descriptions vendor extensions.
+  for (const ext of ep.enumExtensions) {
+    const mapPrefix = `${toCamelCase(ep.operationId)}${toPascalCase(ext.paramName)}`;
+    if (ext.varnames) {
+      lines.push(`export const ${mapPrefix}Labels = {`);
+      for (let i = 0; i < ext.values.length; i++) {
+        lines.push(`  ${JSON.stringify(ext.values[i])}: ${JSON.stringify(ext.varnames[i] ?? ext.values[i])},`);
+      }
+      lines.push(`} as const;`, '');
+    }
+    if (ext.descriptions) {
+      lines.push(`export const ${mapPrefix}Descriptions = {`);
+      for (let i = 0; i < ext.values.length; i++) {
+        lines.push(`  ${JSON.stringify(ext.values[i])}: ${JSON.stringify(ext.descriptions[i] ?? '')},`);
+      }
+      lines.push(`} as const;`, '');
+    }
+  }
   if (!isGet && ep.hasBody && ep.bodyContentType) {
     if (ep.isBinaryBody) {
       // Binary content (octet-stream, pdf, image/*…): use Blob | ArrayBuffer directly.