Nx Plugin OpenAPI

A powerful Nx plugin ecosystem for generating API client code from OpenAPI specifications. This monorepo provides a flexible, plugin-based architecture that supports multiple code generators.

Packages

Package	Description	npm
@nx-plugin-openapi/core	Core plugin system with executor and generators
@nx-plugin-openapi/plugin-openapi	Plugin for OpenAPI Generator
@nx-plugin-openapi/plugin-hey-api	Plugin for hey-api/openapi-ts
@lambda-solutions/nx-plugin-openapi	Legacy package (OpenAPI Generator only)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   @nx-plugin-openapi/core                    │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │  generate-api   │  │  Plugin Loader  │  │ Auto Install │ │
│  │   executor      │  │                 │  │              │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┴───────────────────┐
          ▼                                       ▼
┌────────────────────────┐           ┌────────────────────────┐
│ @nx-plugin-openapi/    │           │ @nx-plugin-openapi/    │
│   plugin-openapi       │           │   plugin-hey-api       │
│                        │           │                        │
│ Uses @openapitools/    │           │ Uses @hey-api/         │
│ openapi-generator-cli  │           │ openapi-ts             │
└────────────────────────┘           └────────────────────────┘

Quick Start

Installation

# Install the core package
nx add @nx-plugin-openapi/core

# Install a generator plugin (choose one or both)
npm install --save-dev @nx-plugin-openapi/plugin-openapi  # For OpenAPI Generator
npm install --save-dev @nx-plugin-openapi/plugin-hey-api  # For hey-api

Basic Usage

Execute the following command:

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

This will add a generate-api target 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"
      }
    }
  }
}

Or use the hey-api generator:

{
  "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"
      }
    }
  }
}

Run the generator

nx run my-app:generate-api

Documentation

For comprehensive documentation, visit our documentation site.

• Getting Started
• Installation Guide
• Plugins Overview
• Configuration Reference
• Creating Custom Plugins
• Examples

Features

• Plugin Architecture: Choose between multiple code generators
• Auto-Installation: Plugins are automatically installed when needed
• Nx Integration: Full support for Nx caching, affected commands, and dependency graph
• Multiple Specs: Generate code from multiple OpenAPI specifications in a single target
• Flexible Configuration: Pass generator-specific options via generatorOptions

Available Generators

openapi-tools (via @nx-plugin-openapi/plugin-openapi)

Uses the battle-tested OpenAPI Generator to generate TypeScript Angular clients and more.

Peer dependency: @openapitools/openapi-generator-cli

hey-api (via @nx-plugin-openapi/plugin-hey-api)

Uses hey-api/openapi-ts for modern TypeScript client generation with excellent type safety.

Peer dependency: @hey-api/openapi-ts

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT