tessl/npm-openapi-typescript

Convert OpenAPI 3.0 & 3.1 schemas to TypeScript type definitions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-openapi-typescript
Author: tessl

The openapi-typescript command-line interface provides comprehensive type generation capabilities with extensive configuration options. It supports multiple input formats, advanced type generation features, and integration with build processes.

Capabilities

Basic Command Structure

The CLI follows a simple pattern with an input source and optional configuration flags.

openapi-typescript [input] [options]

Input Sources

The CLI supports multiple input formats for maximum flexibility.

# Local file (YAML or JSON)
openapi-typescript ./api.yaml
openapi-typescript ./api.json

# Remote URL
openapi-typescript https://api.example.com/openapi.json
openapi-typescript https://raw.githubusercontent.com/user/repo/main/openapi.yaml

# Standard input
cat api.yaml | openapi-typescript
curl https://api.example.com/openapi.json | openapi-typescript

# Multiple schemas via Redocly config
openapi-typescript --redocly ./redocly.yaml

Core Options

Essential options for basic CLI usage and output control.

# Help and version
openapi-typescript --help
openapi-typescript --version

# Output control
openapi-typescript ./api.yaml --output ./types.ts
openapi-typescript ./api.yaml -o ./api-types.ts

# Configuration file
openapi-typescript --redocly ./redocly.yaml
openapi-typescript -c ./custom-redocly.yaml

# Validation mode
openapi-typescript ./api.yaml --check

Core Options Reference:

Option	Short	Description
`--help`		Display help information
`--version`		Display version number
`--output`	`-o`	Specify output file path
`--redocly`	`-c`	Path to Redocly configuration file
`--check`		Check that generated types are up-to-date

Type Generation Options

Options controlling how TypeScript types are generated from OpenAPI schemas.

# Export types instead of interfaces
openapi-typescript ./api.yaml -o ./types.ts --export-type

# Generate immutable (readonly) types
openapi-typescript ./api.yaml -o ./types.ts --immutable

# Generate true TypeScript enums
openapi-typescript ./api.yaml -o ./types.ts --enum

# Export enum values as arrays
openapi-typescript ./api.yaml -o ./types.ts --enum --enum-values

# Deduplicate enums when using --enum
openapi-typescript ./api.yaml -o ./types.ts --enum --dedupe-enums

Type Generation Options Reference:

Option	Description	Example Output
`--export-type`	Export `type` instead of `interface`	`export type User = { ... }`
`--immutable`	Generate readonly properties	`readonly name: string`
`--enum`	Export true TS enums instead of unions	`enum Status { ACTIVE = "active" }`
`--enum-values`	Export enum values as arrays	`export const StatusValues = ["active", "inactive"]`
`--dedupe-enums`	Prevent duplicate enum exports	Single enum per unique value set

Schema Handling Options

Advanced options for customizing how OpenAPI schemas are interpreted and converted.

# Treat all objects as having additional properties
openapi-typescript ./api.yaml -o ./types.ts --additional-properties

# Use 'unknown' for empty objects instead of Record<string, never>
openapi-typescript ./api.yaml -o ./types.ts --empty-objects-unknown

# Ignore default values when determining non-nullable types
openapi-typescript ./api.yaml -o ./types.ts --default-non-nullable=false

# Make all properties required by default
openapi-typescript ./api.yaml -o ./types.ts --properties-required-by-default

# Generate tuples with length constraints from arrays
openapi-typescript ./api.yaml -o ./types.ts --array-length

# Convert paths to template literal types
openapi-typescript ./api.yaml -o ./types.ts --path-params-as-types

# Sort object properties alphabetically
openapi-typescript ./api.yaml -o ./types.ts --alphabetize

# Exclude deprecated schema elements
openapi-typescript ./api.yaml -o ./types.ts --exclude-deprecated

Schema Handling Options Reference:

Option	Description	Impact
`--additional-properties`	Treat objects as `additionalProperties: true`	Allows arbitrary properties
`--empty-objects-unknown`	Use `unknown` for empty objects	`unknown` instead of `Record<string, never>`
`--default-non-nullable`	Consider defaults in nullability	More precise optional/required handling
`--properties-required-by-default`	Make all properties required	Override OpenAPI required arrays
`--array-length`	Generate tuples with constraints	`[string, string]` instead of `string[]`
`--path-params-as-types`	Use template literals for paths	`/users/${string}` instead of string
`--alphabetize`	Sort properties alphabetically	Consistent property ordering
`--exclude-deprecated`	Skip deprecated elements	Cleaner generated types

Advanced Options

Specialized options for complex scenarios and advanced use cases.

# Export schema types at root level
openapi-typescript ./api.yaml -o ./types.ts --root-types

# Don't add "Schema" prefix to root types
openapi-typescript ./api.yaml -o ./types.ts --root-types --root-types-no-schema-prefix

# Generate ApiPaths enum for all paths
openapi-typescript ./api.yaml -o ./types.ts --make-paths-enum

# Generate path parameter types automatically  
openapi-typescript ./api.yaml -o ./types.ts --generate-path-params

Advanced Options Reference:

Option	Description	Result
`--root-types`	Export schemas as root-level types	`export type User = ...` alongside components
`--root-types-no-schema-prefix`	Remove "Schema" prefix from root types	`User` instead of `UserSchema`
`--make-paths-enum`	Create enum of all API paths	`enum ApiPaths { GetUsers = "/users" }`
`--generate-path-params`	Generate path parameter types automatically	Additional parameter type definitions

Multiple Schema Configuration

For complex projects with multiple OpenAPI schemas, use Redocly configuration files.

redocly.yaml example:

apis:
  users:
    root: ./schemas/users.yaml
    x-openapi-ts:
      output: ./types/users.ts
      export-type: true
      immutable: true
  
  products:
    root: ./schemas/products.yaml
    x-openapi-ts:
      output: ./types/products.ts
      enum: true
      alphabetize: true

  combined:
    root: ./schemas/combined.yaml
    x-openapi-ts:
      output: ./types/api.ts
      path-params-as-types: true
      make-paths-enum: true

# Generate types for all configured schemas
openapi-typescript --redocly ./redocly.yaml

Common Usage Patterns

Practical examples for typical development scenarios.

Basic Development Workflow:

# Generate types from local schema
openapi-typescript ./api/openapi.yaml --output ./src/types/api.ts

# Watch mode with file watcher (external tool)
npx nodemon --watch api/openapi.yaml --exec "openapi-typescript ./api/openapi.yaml -o ./src/types/api.ts"

Production Build Integration:

# Validate schema and generate types
openapi-typescript ./api/openapi.yaml --check --output ./dist/types.ts

# Advanced production settings
openapi-typescript ./api/openapi.yaml \
  --output ./dist/types.ts \
  --export-type \
  --immutable \
  --alphabetize \
  --exclude-deprecated \
  --enum

Multi-API Project:

# Generate types for multiple related APIs
openapi-typescript ./schemas/auth.yaml -o ./src/types/auth.ts --export-type
openapi-typescript ./schemas/users.yaml -o ./src/types/users.ts --export-type
openapi-typescript ./schemas/orders.yaml -o ./src/types/orders.ts --export-type

Remote Schema Processing:

# Fetch and process remote schema
openapi-typescript https://api.github.com/spec/openapi.json \
  --output ./types/github.ts \
  --immutable \
  --alphabetize

# Process with additional validation
openapi-typescript https://petstore.swagger.io/v2/swagger.json \
  --output ./types/petstore.ts \
  --check \
  --enum \
  --path-params-as-types

Exit Codes and Error Handling

The CLI provides meaningful exit codes for integration with build systems and CI/CD pipelines.

Exit Codes:

0 - Success
1 - General error (invalid schema, file not found, etc.)
2 - Validation error (when using --check)
3 - Network error (for remote URLs)

Error Examples:

# Schema validation failure
$ openapi-typescript ./invalid-schema.yaml
Error: Schema validation failed: ...
$ echo $?
1

# Check mode with outdated types
$ openapi-typescript ./api.yaml --check --output ./types.ts
Error: Generated types are out of date
$ echo $?
2

# Network error
$ openapi-typescript https://invalid-url.com/schema.json
Error: Failed to fetch schema from URL
$ echo $?
3

Integration Examples

Common patterns for integrating with build tools and development workflows.

package.json scripts:

{
  "scripts": {
    "types:generate": "openapi-typescript ./api/schema.yaml -o ./src/types/api.ts",
    "types:check": "openapi-typescript ./api/schema.yaml --check -o ./src/types/api.ts",
    "types:watch": "nodemon --watch api/ --exec npm run types:generate",
    "prebuild": "npm run types:check"
  }
}

GitHub Actions workflow:

name: Generate Types
on: [push, pull_request]
jobs:
  types:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: openapi-typescript ./api/schema.yaml --check -o ./src/types/api.ts

Makefile integration:

.PHONY: types-generate types-check

types-generate:
	openapi-typescript ./api/schema.yaml -o ./src/types/api.ts --export-type --immutable

types-check:
	openapi-typescript ./api/schema.yaml --check -o ./src/types/api.ts

build: types-check
	npm run build

Install with Tessl CLI

npx tessl i tessl/npm-openapi-typescript

docs

typescript-utilities.md

tile.json

tessl/npm-openapi-typescript

cli-interface.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

CLI Interface

Capabilities

Basic Command Structure

Input Sources

Core Options

Type Generation Options

Schema Handling Options

Advanced Options

Multiple Schema Configuration

Common Usage Patterns

Exit Codes and Error Handling

Integration Examples

cli-interface.mddocs/