Configuration

Configuration

The generate-api executor offers extensive configuration options to customize the generated API client code. This page covers all available configuration options and how to use them effectively.

Basic Configuration

At minimum, you need to specify the generator, input specification, and output path:

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

Core Options

These options are available for all generators:

Option	Type	Default	Description
generator	string	"openapi-tools"	Generator plugin to use ("openapi-tools" or "hey-api")
inputSpec	string | object	required	Path to the OpenAPI specification file (local file or URL), or an object for multiple specs
outputPath	string	required	Output directory for the generated client
generatorOptions	object	{}	Plugin-specific options passed to the generator

Generator Selection

generator

Specifies which generator plugin to use:

{
  "generator": "openapi-tools"
}

Available values:

• "openapi-tools" - Uses OpenAPI Generator CLI (default)
• "hey-api" - Uses hey-api/openapi-ts

Plugin-Specific Options

Each generator has its own set of options. Pass them via the generatorOptions property or directly in the options object.

OpenAPI Generator Options

See OpenAPI Generator docs for all available options.

hey-api Options

See hey-api documentation for configuration options. Common options include:

• client - HTTP client to use (e.g., "fetch", "axios")
• plugins - Array of plugins to enable
• schemas - Schema generation options

---

Detailed Options (OpenAPI Generator)

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

Core Options

configFile

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

Path to an OpenAPI Generator configuration file. This allows you to specify detailed generation options in a separate file.

skipValidateSpec

{
  "skipValidateSpec": true
}

Skip validation of the OpenAPI specification. Useful for faster generation when you’re confident your spec is valid.

Authentication & Security

auth

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

Authentication configuration for accessing remote OpenAPI specifications.

Naming & Organization

apiNameSuffix

{
  "apiNameSuffix": "Client"
}

Suffix to append to generated API class names.

apiPackage

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

Package name for API classes.

packageName

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

Package name for the generated client library.

Model Naming

{
  "modelNamePrefix": "Api",
  "modelNameSuffix": "Model",
  "modelPackage": "com.example.models"
}

Project Information

artifactId & artifactVersion

{
  "artifactId": "my-api-client",
  "artifactVersion": "1.0.0"
}

groupId

{
  "groupId": "com.example"
}

Generation Behavior

dryRun

{
  "dryRun": true
}

Perform a dry run without actually generating files. Useful for testing configuration.

enablePostProcessFile

{
  "enablePostProcessFile": true
}

Enable post-processing of generated files.

minimalUpdate

{
  "minimalUpdate": true
}

Only update files that have actually changed.

skipOverwrite

{
  "skipOverwrite": true
}

Skip overwriting existing files.

removeOperationIdPrefix

{
  "removeOperationIdPrefix": true
}

Remove operation ID prefixes from generated method names.

skipOperationExample

{
  "skipOperationExample": true
}

Skip generating operation examples in the code.

strictSpec

{
  "strictSpec": true
}

Use strict specification validation.

Templates & Customization

templateDirectory

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

Directory containing custom templates for code generation.

ignoreFileOverride

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

Path to a custom ignore file.

Advanced Options

globalProperties

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

Global properties passed to the OpenAPI Generator.

httpUserAgent

{
  "httpUserAgent": "MyApp/1.0.0"
}

Custom HTTP user agent string.

releaseNote

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

Release notes for the generated code.

inputSpecRootDirectory

{
  "inputSpecRootDirectory": "specs/"
}

Root directory for input specifications.

invokerPackage

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

Package name for invoker classes.

Git Integration

Git Repository Information

{
  "gitHost": "github.com",
  "gitUserId": "my-username",
  "gitRepoId": "my-api-client"
}

Logging & Debugging

logToStderr

{
  "logToStderr": true
}

Log output to stderr instead of stdout.

Configuration File Example

Instead of specifying all options in project.json, you can use a separate configuration file:

apps/my-app/openapi-config.json

{
  "npmName": "@my-org/api-client",
  "npmVersion": "1.0.0",
  "ngVersion": "17.0.0",
  "providedInRoot": true,
  "withInterfaces": true,
  "useSingleRequestParameter": true,
  "supportsES6": true,
  "modelPropertyNaming": "camelCase",
  "enumPropertyNaming": "UPPERCASE"
}

Then reference it:

project.json

{
  "generate-api": {
    "executor": "@nx-plugin-openapi/core:generate-api",
    "options": {
      "inputSpec": "apps/my-app/swagger.json",
      "outputPath": "libs/api-client/src",
      "configFile": "apps/my-app/openapi-config.json"
    }
  }
}

Environment-Specific Configuration

You can use different configurations for different environments:

project.json

{
  "generate-api": {
    "executor": "@nx-plugin-openapi/core:generate-api",
    "options": {
      "inputSpec": "apps/my-app/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 specific configuration:

nx run my-app:generate-api:development

Next Steps

• View Examples for common configuration patterns
• API Reference for complete option details
• Nx Integration for advanced Nx workspace setup