OpenAPI Generator

The @ng-forge/openapi-generator reads your OpenAPI 3.x spec and produces ready-to-use FormConfig objects and TypeScript interfaces. No manual field wiring: your API contract drives your forms.

Key features:

• Generates as const satisfies FormConfig for full type inference
• Maps OpenAPI types, formats, and constraints to field types and validators
• Interactive mode for resolving ambiguous field types (e.g. input vs textarea)
• Watch mode for regeneration on spec changes
• Persists decisions in a config file for reproducible builds

Installation

Run directly with npx:

npx @ng-forge/openapi-generator --spec ./openapi.yaml --output ./src/forms

Or install as a dev dependency:

Quick Start

Given a Petstore-like OpenAPI spec:

openapi: 3.0.3
info:
  title: Petstore
  version: 1.0.0
paths:
  /pets:
    post:
      operationId: createPet
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                age:
                  type: integer
                  minimum: 0
                email:
                  type: string
                  format: email
                status:
                  type: string
                  enum: [available, pending, sold]

Run the generator:

npx @ng-forge/openapi-generator --spec ./petstore.yaml --output ./src/forms

This produces:

src/forms/forms/create-pet.form.ts

// @generated by @ng-forge/openapi-generator
import type { FormConfig } from '@ng-forge/dynamic-forms';

export const createPetFormConfig = {
  fields: [
    {
      key: 'name',
      type: 'input',
      label: 'Name',
      props: { type: 'text' },
      validators: [{ type: 'required' }, { type: 'minLength', value: 1 }, { type: 'maxLength', value: 100 }],
    },
    {
      key: 'age',
      type: 'input',
      label: 'Age',
      props: { type: 'number' },
      validators: [{ type: 'min', value: 0 }],
    },
    {
      key: 'email',
      type: 'input',
      label: 'Email',
      props: { type: 'email' },
      validators: [{ type: 'email' }],
    },
    {
      key: 'status',
      type: 'select',
      label: 'Status',
      options: [
        { label: 'Available', value: 'available' },
        { label: 'Pending', value: 'pending' },
        { label: 'Sold', value: 'sold' },
      ],
    },
  ],
} as const satisfies FormConfig;

src/forms/types/create-pet.types.ts

// @generated by @ng-forge/openapi-generator
export interface CreatePetFormValue {
  name: string;
  age?: number;
  email?: string;
  status?: 'available' | 'pending' | 'sold';
}

Both directories include barrel index.ts files for convenient imports.

CLI Reference

ng-forge-generator [options]

OpenAPI to Field Type Mapping

The generator maps OpenAPI schema types and formats to @ng-forge/dynamic-forms field types:

Nullable Values

OpenAPI nullability is preserved end-to-end:

See Nullable values in Configuration for runtime behavior and the read-side caveat.

Ambiguous Field Types

Some mappings have alternatives. In interactive mode, the CLI prompts you to choose:

In non-interactive mode (--interactive none), the Default column is used automatically.

Validator Mapping

OpenAPI schema constraints map directly to @ng-forge/dynamic-forms validators:

Schema Support

Request Body Content Types

Request body schemas are read from application/json, multipart/form-data, or application/x-www-form-urlencoded, in that preference order when an endpoint declares more than one.

Binary file properties (type: string with format: binary, including arrays of them) are skipped with a warning since no file upload field type exists yet. An endpoint whose body contains only binary properties produces no form and is skipped entirely.

Config File

The generator persists your choices in .ng-forge-generator.json:

{
  "spec": "./openapi.yaml",
  "output": "./src/forms",
  "endpoints": ["POST:/pets", "GET:/pets/{id}"],
  "decisions": {
    "description": "textarea",
    "age": "slider"
  },
  "readOnly": true
}

On subsequent runs, persisted decisions are reused, so interactive prompts only appear for new or changed fields.

Interactive vs Non-Interactive Mode

Interactive (--interactive full) is the default:

1. Prompts you to select which endpoints to generate forms for (all endpoints are pre-selected; uncheck the ones you don't want)
2. Prompts for each ambiguous field type choice
3. Saves decisions to the config file

Non-interactive (--interactive none):

• Uses all endpoints, or filters by --endpoints flag
• Uses default field type choices for ambiguous fields
• No prompts, suitable for CI/CD pipelines

Watch Mode

npx @ng-forge/openapi-generator \
  --spec ./openapi.yaml \
  --output ./src/forms \
  --watch

Watch mode monitors your spec file and regenerates forms on changes:

• Uses a 500ms debounce to avoid thrashing
• Runs in non-interactive mode (uses persisted decisions)
• Press Ctrl+C to stop

Output Structure

Generated files follow this layout:

<output-dir>/
├── forms/
│   ├── create-pet.form.ts
│   ├── list-pets.form.ts
│   └── index.ts
└── types/
    ├── create-pet.types.ts
    ├── list-pets.types.ts
    └── index.ts

File names are derived from operationId if available, otherwise from the HTTP method and path (e.g. POST /pets/{id}/tags becomes post-pets-by-id-tags).

GET Endpoints

By default, GET endpoints are included with editable fields, just like POST/PUT/PATCH. Use the --read-only flag to generate GET endpoint fields with disabled: true:

npx @ng-forge/openapi-generator \
  --spec ./openapi.yaml \
  --output ./src/forms \
  --read-only

Top-level array responses are always skipped with a warning.

Programmatic API

The package exports its internals for programmatic use:

import {
  // Parsing
  parseOpenAPISpec,
  extractEndpoints,

  // Mapping
  mapSchemaToFieldType,
  mapSchemaToValidators,
  mapSchemaToFields,

  // Generation
  generateFormConfig,
  generateInterface,
  generateBarrel,
  writeGeneratedFiles,

  // Configuration
  loadConfig,
  saveConfig,

  // CLI
  run,
} from '@ng-forge/openapi-generator';

Use these to integrate form generation into custom build pipelines, Nx generators, or CI workflows.