Getting Started with nx-plugin-openapi

Generate type-safe API clients from OpenAPI specifications in your Nx workspace. This guide covers setup, configuration, and usage of the new plugin-based architecture of the former @lambda-solutions/nx-plugin-openapi.

Overview

The @nx-plugin-openapi ecosystem provides a flexible, extensible system for generating API clients:

@nx-plugin-openapi/core          # Core executor and generators
├── plugin-openapi               # OpenAPI Generator CLI wrapper
└── plugin-hey-api               # hey-api/openapi-ts wrapper

Choose your generator based on your needs:

• openapi-tools: Mature, multi-language support, Angular-optimized
• hey-api: Modern TypeScript-first, multiple HTTP clients (fetch, axios)

Installation

Step 1: Add Core Package

nx add @nx-plugin-openapi/core

This installs the core package and runs the init generator, which configures caching in nx.json.

Step 2: Install Your Preferred Generator Plugin

Option A: OpenAPI Generator (recommended for Angular)

npm install -D @nx-plugin-openapi/plugin-openapi @openapitools/openapi-generator-cli

Option B: hey-api (recommended for modern TypeScript)

npm install -D @nx-plugin-openapi/plugin-hey-api @hey-api/openapi-ts

You can install both if working with different project requirements.

Adding a Generate Target

Interactive Setup

Run the generator to add a target to your project:

nx g @nx-plugin-openapi/core:add-generate-api-target

You’ll be prompted for:

• Target project
• OpenAPI spec path
• Output directory
• Generator plugin to use
• Additional options

Manual Configuration

Add the target directly to your project.json:

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "generator": "openapi-tools",
        "inputSpec": "apps/my-app/swagger.json",
        "outputPath": "libs/api-client/src"
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}

Running the Generator

# Single project
nx run my-app:generate-api

# All projects with generate-api target
nx run-many -t generate-api

# Only affected projects
nx affected -t generate-api

Configuration Options

Core Options

Multiple Specifications

Generate clients for multiple APIs in one target:

{
  "options": {
    "inputSpec": {
      "users-api": "apis/users.yaml",
      "products-api": "apis/products.yaml"
    },
    "outputPath": "libs/api-clients/src"
  }
}

Output structure:

libs/api-clients/src/
├── users-api/
└── products-api/

OpenAPI Generator Plugin

The openapi-tools generator wraps @openapitools/openapi-generator-cli. Pass any CLI option through generatorOptions.

Example: Angular Client

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "generator": "openapi-tools",
        "inputSpec": "apps/my-app/swagger.json",
        "outputPath": "libs/api-client/src",
        "generatorOptions": {
          "skipValidateSpec": true,
          "globalProperties": {
            "supportsES6": "true",
            "providedInRoot": "true",
            "withInterfaces": "true"
          }
        }
      }
    }
  }
}

Using a Config File

Create openapi-config.json:

{
  "fileNaming": "kebab-case",
  "ngVersion": "19.0.0",
  "providedIn": "root",
  "serviceFileSuffix": ".api.service",
  "serviceSuffix": "ApiService"
}

Reference in target:

{
  "generatorOptions": {
    "configFile": "apps/my-app/openapi-config.json"
  }
}

Common Options

hey-api Plugin

The hey-api generator uses @hey-api/openapi-ts for modern TypeScript generation.

Example: Fetch Client

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "generator": "hey-api",
        "inputSpec": "apps/my-app/openapi.yaml",
        "outputPath": "libs/api-client/src",
        "generatorOptions": {
          "client": "fetch",
          "plugins": [
            "@hey-api/schemas",
            "@hey-api/services",
            "@hey-api/types"
          ]
        }
      }
    }
  }
}

Client Options

Workspace Configuration

The init generator configures nx.json for caching:

{
  "targetDefaults": {
    "@nx-plugin-openapi/core:generate-api": {
      "cache": true,
      "inputs": [
        "{projectRoot}/swagger.json",
        "{projectRoot}/openapitools.json"
      ]
    }
  }
}

Nx caches generation results. Re-running generate-api with unchanged inputs skips generation.

Complete Example

Project Structure

my-workspace/
├── apps/
│   └── my-app/
│       ├── src/
│       ├── swagger.json
│       └── project.json
├── libs/
│   └── api-client/
│       └── src/
├── nx.json
└── package.json

apps/my-app/project.json

{
  "name": "my-app",
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "generator": "openapi-tools",
        "inputSpec": "apps/my-app/swagger.json",
        "outputPath": "libs/api-client/src",
        "generatorOptions": {
          "skipValidateSpec": true,
          "globalProperties": {
            "providedInRoot": "true"
          }
        }
      },
      "outputs": ["{options.outputPath}"]
    },
    "build": {
      "dependsOn": ["generate-api"]
    }
  }
}

Usage

# Generate the API client
nx run my-app:generate-api

# Build (auto-generates API first)
nx run my-app:build

Auto-Installation

When using a generator plugin for the first time, the core package detects missing dependencies and prompts for installation in interactive terminals. In CI environments, install dependencies explicitly.

Summary

1. Install @nx-plugin-openapi/core via nx add
2. Install your preferred generator plugin
3. Add generate-api target to your project
4. Configure inputSpec, outputPath, and generator-specific options
5. Run nx run <project>:generate-api

The plugin system supports custom generators by implementing the GeneratorPlugin interface from @nx-plugin-openapi/core.