TypeScript Type Generator

This tool automatically generates TypeScript type definitions from an OpenAPI schema. It's specifically designed to work with eBRÁNA Fenix application built with Symfony API Platform.

Important Note

⚠️ This tool is specifically designed for the eBRÁNA Fenix application using Symfony API Platform's API documentation format.

It is not a general-purpose OpenAPI to TypeScript converter and may not work with other API schemas that don't follow the same structure. The tool expects the specific JSON format used by Symfony API Platform.

Features

• Fetches API schema from Symfony API Platform OpenAPI endpoint
• Filters for specific endpoint types
• Converts OpenAPI schemas to TypeScript types
• Shows diffs when updating existing type files
• Confirms changes before overwriting existing files
• Handles nullable fields as optional properties
• Properly handles nested arrays and object types
• Supports schema references ($ref) across types with intelligent imports
• Detects and generates dependent types automatically
• Supports self-signed certificates with SSL bypass options
• Configurable API endpoint via command line flag

Installation

Global Installation (recommended)

Install globally to use as a command-line tool:

npm install -g @ondrej_burval/ts-type-generator

Local Installation

Install locally in your project:

npm install --save-dev @ondrej_burval/ts-type-generator

npx Usage (no installation required)

You can also run the tool directly with npx without installing:

npx @ondrej_burval/ts-type-generator

The npx command will download the package temporarily, run it, and then clean up afterward. This is ideal for one-time use or trying the tool without installing it.

Setup

1. Create a types directory to store generated types:

mkdir -p types

Usage

As a Global Command or with npx

# Using global installation
ts-type-generator

# Using npx without installation
npx @ondrej_burval/ts-type-generator

To generate types for a specific resource only:

# Using positional argument (traditional)
ts-type-generator VatStf

# Using the --resource flag
ts-type-generator --resource VatStf

To use a different API URL:

ts-type-generator --web https://main.fenix-devel.cz/fapi

Combining multiple options:

ts-type-generator --web https://main.fenix-devel.cz/fapi --resource VatStf --ignore-ssl -A

Command Line Flags

| Flag | Description | |------|-------------| | -A | Auto-accept all file overwrites without prompting | | -N | Auto-reject all file overwrites without prompting | | -F | Show full file content when displaying changes | | --web <URL> | Specify the API base URL (default: https://fenix.loc/fapi) | | --resource <name> | Generate types for a specific resource only | | --ignore-ssl | Ignore SSL certificate errors (for self-signed certificates) | | --use-system-ca | Use system CA certificates (run node with this flag) |

API URL Configuration

By default, the script connects to https://fenix.loc/fapi, which is intended for local development of Fenix application.

• For local URLs (containing 'localhost', '.loc/', or '127.0.0.1'), SSL verification is automatically ignored.
• For production or other environments, use the --web flag to specify the target API URL.

Example for production:

ts-type-generator --web https://main.fenix-devel.cz/fapi

SSL Certificate Issues

If you encounter SSL certificate errors, you have several options:

1. Use the --ignore-ssl flag to bypass certificate validation:

   ts-type-generator --ignore-ssl

2. Run Node.js with the --use-system-ca flag to use system certificates:

   node --use-system-ca $(which ts-type-generator)

3. Set the NODE_TLS_REJECT_UNAUTHORIZED environment variable (not recommended for production):

   NODE_TLS_REJECT_UNAUTHORIZED=0 ts-type-generator

Smart Reference Handling

When the generator encounters references to other types (like BreadCrumbStf), it will:

1. Check if the referenced type already exists in your types directory
2. If it exists, it will automatically add the proper import statement
3. If it doesn't exist, it will prompt you to generate it
4. If you agree, it will fetch the schema for that type and generate it too
5. If you decline, it will use any as the type instead (clearly indicated during the prompt)

This ensures a complete and interconnected type system without manually handling dependencies.

Expected Output Structure

The tool generates TypeScript type definitions with proper absolute imports for referenced types.

Example output:

import type { BreadCrumbStf } from "@/types/BreadCrumbStf";
import type { ProductStf } from "@/types/ProductStf";

export type ProductDetailStf = {
    id?: string;
    name: string;
    description: string;
    price: number;
    categories: string[];
    tags: Array<{
        id: number;
        name: string;
    }>;
    breadcrumb: BreadCrumbStf;  // Reference to another type
    relatedProducts: ProductStf[];  // Array of referenced types
    // Other properties from API...
}

Example Type Output

export type VatStf = {
    id?: string;
    name: string;
    value: number;
    country: string;
}

Notes

• The types directory is excluded from git (except for the .gitkeep file)
• The script validates the existence of the types directory before running