Quick Start

Quick Start

This guide will help you generate your first API client using the Nx Plugin OpenAPI.

Recommended: add-client

The add-client generator sets up a client without project.json files. Nx infers the targets and libs from a client definition (see Inferred Targets).

nx g @nx-plugin-openapi/core:add-client petstore \
  --directory=libs/shared/petstore \
  --scope=shared \
  --spec=https://petstore3.swagger.io/api/v3/openapi.json \
  --adapter=openapi-tools

The generator:

• downloads a remote --spec once to libs/shared/petstore/petstore.openapi.json (or .yaml) and stores the URL for update-spec. The file is written as downloaded and added to .prettierignore, so update-spec --check compares exact content. A local path is referenced as is.
• writes libs/shared/petstore/openapi-client.json
• registers @nx-plugin-openapi/core/plugin in nx.json if missing
• with --split (default true): adds tsconfig.base.json paths for @<npm-scope>/petstore-types, -api and -core (change the prefix with --importPrefix) and a README.md per lib
• adds the generated dirs to .gitignore (disable with --addToGitignore=false)
• writes no project.json

Note

The CLI option is --adapter, not --generator: nx g reserves --generator. In openapi-client.json the field is generator.

Option	Default	Description
name		Client name, e.g. petstore
directory		Client directory
scope		Adds the tag scope:<scope>
spec		Local spec path or URL
adapter	openapi-tools	openapi-tools or hey-api
generatorOptions		Generator options, e.g. --generatorOptions.client=fetch
split	true	Split into types, api and core libs
importPrefix	npm scope	Prefix of the lib aliases

Then generate and use the client:

nx show projects                    # petstore, petstore-types, petstore-api, petstore-core
nx run petstore:generate            # cached, re-runs only when the spec or definition changes
nx build petstore-api               # generates first
nx run petstore:update-spec         # refresh the committed spec from the URL
nx run petstore:update-spec --check # CI: fail if the remote spec changed

import { PetService } from '@acme/petstore-api';
import { Pet } from '@acme/petstore-types';

The rest of this guide shows the manual setup with an explicit project.json target.

Step 1: Prepare Your OpenAPI Specification

You’ll need an OpenAPI specification file. This can be:

• A local JSON or YAML file
• A remote URL endpoint

For this example, we’ll use a local file. Create a simple OpenAPI spec:

apps/my-app/swagger.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      }
    }
  }
}

Step 2: Configure the Executor

Add the generate-api executor to your project’s project.json.

Using the Generator (Recommended)

The easiest way is to use the interactive generator:

nx generate @nx-plugin-openapi/core:add-generate-api-target --project=my-app

The generator will walk you through the configuration options.

Manual Configuration

You can also manually add the executor configuration to your project.json file:

Using OpenAPI Generator (openapi-tools)

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": "apps/my-app/src/app/api"
      },
      "outputs": ["{options.outputPath}"]
    },
    "build": {
      "dependsOn": ["generate-api"]
    }
  }
}

Using hey-api

apps/my-app/project.json

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

Generator Selection

• openapi-tools: Best for Angular projects needing injectable services, or when using OpenAPI Generator’s extensive template ecosystem.
• hey-api: Best for modern TypeScript projects wanting simpler, more type-safe generated code.

Step 3: Generate the API Client

Run the executor to generate your API client:

nx run my-app:generate-api

You should see output similar to:

✔ Starting to generate API from provided OpenAPI spec...
✔ Cleaning outputPath libs/api-client/src first
✔ API generation completed successfully.

Step 4: Examine the Generated Code

The generated code structure varies based on the generator you chose:

OpenAPI Generator (openapi-tools) Output

libs/api-client/src/
├── api/
│   ├── api.ts
│   ├── default.service.ts
│   └── ...
├── model/
│   ├── models.ts
│   ├── user.ts
│   └── ...
├── configuration.ts
├── index.ts
└── variables.ts

hey-api Output

libs/api-client/src/
├── client/
│   └── client.ts
├── schemas/
│   └── ...
├── services/
│   └── ...
├── types/
│   └── ...
└── index.ts

Step 5: Set Up Nx Integration (Optional)

For better integration with Nx’s build system, configure target defaults in your nx.json:

nx.json

{
  "targetDefaults": {
    "generate-api": {
      "cache": true,
      "inputs": ["{projectRoot}/swagger.json", "{projectRoot}/openapi.yaml", "{projectRoot}/openapi-config.json"]
    },
    "build": {
      "dependsOn": ["^build", "^generate-api", "generate-api"]
    }
  }
}

This configuration:

• Enables caching for the generate-api executor
• Makes builds depend on API generation
• Includes relevant input files for cache invalidation

Step 6: Use the Generated Client

The usage of the generated client depends on which generator you chose:

• OpenAPI Generator: See the official documentation for Angular integration.
• hey-api: See the hey-api documentation for usage examples.

Next Steps

Congratulations! You’ve successfully generated your first API client. Here’s what you can do next:

• Explore Configuration Options - Learn about advanced configuration options
• View Examples - See more complex usage patterns
• API Reference - Complete reference for all available options

Common Issues

Plugin Not Found

If you see an error about a plugin not being found, ensure the plugin package is installed:

# For openapi-tools
npm install --save-dev @nx-plugin-openapi/plugin-openapi @openapitools/openapi-generator-cli

# For hey-api
npm install --save-dev @nx-plugin-openapi/plugin-hey-api @hey-api/openapi-ts

Output Directory Conflicts

The plugin automatically cleans the output directory before generation. Make sure the outputPath doesn’t contain important files that shouldn’t be deleted.