generate-api Executor

The generate-api executor generates API client code from OpenAPI specifications using your choice of generator plugin.

Usage

nx run <project>:generate-api

Basic Configuration

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

Core Options

These options are available for all generator plugins.

`generator`

Type: string
Default: "openapi-tools"
Required: No
Description: Specifies which generator plugin to use

Available values:

"openapi-tools" - Uses OpenAPI Generator CLI (@openapitools/openapi-generator-cli)
"hey-api" - Uses hey-api (@hey-api/openapi-ts)

Examples:

{
  "generator": "openapi-tools"
}

{
  "generator": "hey-api"
}

`inputSpec`

Type: string | Record<string, string>
Required: Yes
Description: Path to the OpenAPI specification file(s) or URL(s)

The input specification can be:

A single string: Path to one OpenAPI specification (backward compatible)
An object: Multiple specifications mapped by service name (for microservices)

Single Specification (String)

For projects with a single API:

{
  "inputSpec": "apps/my-app/swagger.json"
}

{
  "inputSpec": "https://api.example.com/swagger.json"
}

Multiple Specifications (Object)

For microservice architectures with multiple APIs:

{
  "inputSpec": {
    "ms-product": "apps/my-app/ms-product.json",
    "ms-user": "apps/my-app/ms-user.json",
    "ms-inventory": "apps/my-app/ms-inventory.json"
  }
}

When using multiple specifications:

Each key becomes a subdirectory name under outputPath
Each API is generated in its own subdirectory
All configured options are applied to each generation

Generated structure for multiple specs:

libs/api/src/
  ms-product/
    // generated API for product service
  ms-user/
    // generated API for user service
  ms-inventory/
    // generated API for inventory service

`outputPath`

Type: string
Required: Yes
Description: Output directory for the generated API client code

The output directory will be cleaned before generation. Relative paths are resolved from the workspace root.

Examples:

{
  "outputPath": "libs/api-client/src"
}

{
  "outputPath": "apps/my-app/src/app/generated"
}

`generatorOptions`

Type: object
Default: {}
Required: No
Description: Plugin-specific options passed to the generator

This object allows you to pass options specific to the selected generator. The available options depend on which generator you’re using.

Example for OpenAPI Generator:

{
  "generatorOptions": {
    "configFile": "apps/my-app/openapi-config.json",
    "skipValidateSpec": true,
    "globalProperties": {
      "supportsES6": "true"
    }
  }
}

Example for hey-api:

{
  "generatorOptions": {
    "client": "fetch",
    "plugins": ["@hey-api/schemas"]
  }
}

OpenAPI Generator Options

The following options apply when using generator: "openapi-tools". They can be specified directly in options or within generatorOptions.

`configFile`

Type: string
Default: undefined
Description: Path to OpenAPI Generator configuration file

Allows you to specify detailed generation options in a separate JSON file.

Example:

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

`skipValidateSpec`

Type: boolean
Default: false
Description: Skip validation of the OpenAPI specification

Set to true for faster generation when you’re confident your specification is valid.

Example:

{
  "skipValidateSpec": true
}

Authentication & Security

`auth`

Type: string
Default: undefined
Description: Authentication configuration for accessing remote specifications

Example:

{
  "auth": "bearer:your-api-token"
}

Naming & Package Configuration

`apiNameSuffix`

Type: string
Default: undefined
Description: Suffix to append to generated API class names

Example:

{
  "apiNameSuffix": "Client"
}

`apiPackage`

Type: string
Default: undefined
Description: Package name for API classes

Example:

{
  "apiPackage": "com.example.api"
}

`packageName`

Type: string
Default: undefined
Description: Package name for the generated client library

Example:

{
  "packageName": "@my-org/api-client"
}

`modelNamePrefix`

Type: string
Default: undefined
Description: Prefix for generated model class names

Example:

{
  "modelNamePrefix": "Api"
}

`modelNameSuffix`

Type: string
Default: undefined
Description: Suffix for generated model class names

Example:

{
  "modelNameSuffix": "Model"
}

`modelPackage`

Type: string
Default: undefined
Description: Package name for model classes

Example:

{
  "modelPackage": "com.example.models"
}

Project Metadata

`artifactId`

Type: string
Default: undefined
Description: Artifact ID for the generated code

Example:

{
  "artifactId": "my-api-client"
}

`artifactVersion`

Type: string
Default: undefined
Description: Version of the generated artifact

Example:

{
  "artifactVersion": "1.0.0"
}

`groupId`

Type: string
Default: undefined
Description: Group ID for the generated code

Example:

{
  "groupId": "com.example"
}

Generation Behavior

`dryRun`

Type: boolean
Default: false
Description: Perform a dry run without actually generating files

Useful for testing configuration without creating files.

Example:

{
  "dryRun": true
}

`enablePostProcessFile`

Type: boolean
Default: false
Description: Enable post-processing of generated files

Example:

{
  "enablePostProcessFile": true
}

`minimalUpdate`

Type: boolean
Default: false
Description: Only update files that have actually changed

Example:

{
  "minimalUpdate": true
}

`skipOverwrite`

Type: boolean
Default: false
Description: Skip overwriting existing files

Example:

{
  "skipOverwrite": true
}

`removeOperationIdPrefix`

Type: boolean
Default: false
Description: Remove operation ID prefixes from generated method names

Example:

{
  "removeOperationIdPrefix": true
}

`skipOperationExample`

Type: boolean
Default: false
Description: Skip generating operation examples in the code

Example:

{
  "skipOperationExample": true
}

`strictSpec`

Type: boolean
Default: false
Description: Use strict specification validation

Example:

{
  "strictSpec": true
}

Templates & Customization

`templateDirectory`

Type: string
Default: undefined
Description: Directory containing custom templates for code generation

Example:

{
  "templateDirectory": "apps/my-app/templates"
}

`ignoreFileOverride`

Type: string
Default: undefined
Description: Path to a custom ignore file

Example:

{
  "ignoreFileOverride": "apps/my-app/.openapi-generator-ignore"
}

Advanced Configuration

`globalProperties`

Type: object
Default: undefined
Description: Global properties for the OpenAPI Generator

An object where keys are property names and values are property values.

Example:

{
  "globalProperties": {
    "supportsES6": "true",
    "npmName": "@my-org/api-client",
    "npmVersion": "1.0.0",
    "providedInRoot": "true",
    "withInterfaces": "true"
  }
}

`httpUserAgent`

Type: string
Default: undefined
Description: Custom HTTP user agent string

Example:

{
  "httpUserAgent": "MyApp/1.0.0"
}

`releaseNote`

Type: string
Default: undefined
Description: Release notes for the generated code

Example:

{
  "releaseNote": "Initial release of the API client"
}

`inputSpecRootDirectory`

Type: string
Default: undefined
Description: Root directory for input specifications

Example:

{
  "inputSpecRootDirectory": "specs/"
}

`invokerPackage`

Type: string
Default: undefined
Description: Package name for invoker classes

Example:

{
  "invokerPackage": "com.example.invoker"
}

Git Integration

`gitHost`

Type: string
Default: undefined
Description: Git host for the repository

Example:

{
  "gitHost": "github.com"
}

`gitUserId`

Type: string
Default: undefined
Description: Git user ID

Example:

{
  "gitUserId": "my-username"
}

`gitRepoId`

Type: string
Default: undefined
Description: Git repository ID

Example:

{
  "gitRepoId": "my-api-client"
}

Logging & Debugging

`logToStderr`

Type: boolean
Default: false
Description: Log output to stderr instead of stdout

Example:

{
  "logToStderr": true
}

Complete Example

Here’s a comprehensive example showing many options:

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src",
        "configFile": "apps/demo/openapi-config.json",
        "packageName": "@my-org/demo-api-client",
        "apiNameSuffix": "Service",
        "modelNamePrefix": "Api",
        "modelNameSuffix": "Model",
        "skipValidateSpec": false,
        "strictSpec": true,
        "globalProperties": {
          "supportsES6": "true",
          "npmName": "@my-org/demo-api-client",
          "npmVersion": "1.0.0",
          "providedInRoot": "true",
          "withInterfaces": "true"
        }
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}

Multiple APIs Example

For microservice architectures:

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "inputSpec": {
          "auth-service": "apis/auth-service.yaml",
          "product-service": "apis/product-service.yaml",
          "order-service": "apis/order-service.yaml",
          "payment-service": "apis/payment-service.yaml"
        },
        "outputPath": "libs/api-clients/src",
        "packageName": "@my-org/api-clients",
        "apiNameSuffix": "ApiService",
        "modelNamePrefix": "Api",
        "globalProperties": {
          "supportsES6": "true",
          "providedInRoot": "true",
          "withInterfaces": "true"
        }
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}

This will generate:

libs/api-clients/src/
  auth-service/
    // Auth API client
  product-service/
    // Product API client
  order-service/
    // Order API client
  payment-service/
    // Payment API client

Environment-Specific Configuration

Use configurations for different environments:

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src"
      },
      "configurations": {
        "development": {
          "inputSpec": "http://localhost:3000/api/swagger.json",
          "skipValidateSpec": true
        },
        "production": {
          "inputSpec": "https://api.prod.example.com/swagger.json",
          "strictSpec": true
        }
      }
    }
  }
}

Run with configuration:

nx run demo:generate-api:development

hey-api Generator Options

The following options apply when using generator: "hey-api". Pass them via generatorOptions.

Common hey-api Options

Option	Type	Description
`client`	string	HTTP client to use (`"fetch"`, `"axios"`, etc.)
`plugins`	array	Array of plugins to enable
`schemas`	object	Schema generation configuration
`services`	object	Service generation configuration
`types`	object	Type generation configuration

For a complete list of options, see the hey-api documentation.

hey-api Example

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

hey-api Multiple Services Example

{
  "targets": {
    "generate-api": {
      "executor": "@nx-plugin-openapi/core:generate-api",
      "options": {
        "generator": "hey-api",
        "inputSpec": {
          "users": "apis/users-api.yaml",
          "products": "apis/products-api.yaml"
        },
        "outputPath": "libs/api-clients/src",
        "generatorOptions": {
          "client": "axios"
        }
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}