Examples

This page provides practical examples for common use cases with the generate-api executor.

Basic Examples

Local OpenAPI Specification

Generate an API client from a local OpenAPI specification file:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src"
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}

Remote OpenAPI Specification

Generate from a remote URL:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "https://api.example.com/swagger.json",
        "outputPath": "libs/api-client/src"
      }
    }
  }
}

Configuration Examples

With Custom Configuration File

Use a separate configuration file for detailed OpenAPI Generator options:

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

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/openapi.json",
        "outputPath": "libs/api-client/src",
        "configFile": "apps/demo/openapi-config.json"
      }
    }
  }
}

Skip Validation for Faster Generation

When you’re confident your OpenAPI spec is valid, skip validation for faster generation:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src",
        "skipValidateSpec": true
      }
    }
  }
}

Advanced Examples

Custom Package Configuration

Generate with custom package information and naming:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src",
        "packageName": "@my-org/demo-api-client",
        "apiNameSuffix": "Service",
        "modelNamePrefix": "Api",
        "modelNameSuffix": "Model"
      }
    }
  }
}

Global Properties Configuration

Use global properties for fine-tuned control:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src",
        "globalProperties": {
          "supportsES6": "true",
          "npmName": "@my-org/api-client",
          "npmVersion": "2.0.0",
          "providedInRoot": "true",
          "withInterfaces": "true",
          "useSingleRequestParameter": "true",
          "enumPropertyNaming": "UPPERCASE"
        }
      }
    }
  }
}

Authentication for Remote APIs

Access protected OpenAPI specifications:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "https://api.example.com/swagger.json",
        "outputPath": "libs/api-client/src",
        "auth": "bearer:your-api-token-here",
        "httpUserAgent": "MyApp/1.0.0"
      }
    }
  }
}

Custom Templates

Use custom templates for code generation:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src",
        "templateDirectory": "apps/demo/templates",
        "enablePostProcessFile": true
      }
    }
  }
}

Environment-Specific Examples

Development vs Production

Configure different behaviors for different environments:

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

Usage:

# Development environment
nx run demo:generate-api:development

# Production environment
nx run demo:generate-api:production

# Test run
nx run demo:generate-api:test

Multiple API Clients

Separate Targets for Different APIs

Generate multiple API clients from different specifications:

{
  "targets": {
    "generate-user-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/user-api.json",
        "outputPath": "libs/user-api-client/src",
        "packageName": "@my-org/user-api-client"
      }
    },
    "generate-product-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/product-api.json",
        "outputPath": "libs/product-api-client/src",
        "packageName": "@my-org/product-api-client"
      }
    },
    "generate-all-apis": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "nx run demo:generate-user-api",
          "nx run demo:generate-product-api"
        ],
        "parallel": true
      }
    }
  }
}

Monorepo Examples

Shared Library Generation

Generate a shared API client library used across multiple apps:

{
  "name": "shared-api-client",
  "targets": {
    "generate": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "https://api.company.com/swagger.json",
        "outputPath": "libs/shared-api-client/src/lib/generated",
        "packageName": "@my-org/shared-api-client",
        "globalProperties": {
          "providedInRoot": "true",
          "ngVersion": "17.0.0"
        }
      }
    },
    "build": {
      "dependsOn": ["generate"]
    }
  }
}

Workspace-Level Configuration

Configure API generation at the workspace level in nx.json:

{
  "targetDefaults": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "cache": true,
      "inputs": [
        "{projectRoot}/swagger.json",
        "{projectRoot}/openapi.json",
        "{projectRoot}/api-spec.yaml",
        "{projectRoot}/openapi-config.json"
      ]
    },
    "build": {
      "dependsOn": ["^build", "^generate-api", "generate-api"]
    }
  }
}

CI/CD Examples

GitHub Actions

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - run: npm ci

      # Generate API clients
      - name: Generate API Clients
        run: nx run-many --target=generate-api --all

      # Build all projects
      - name: Build
        run: nx run-many --target=build --all

      # Run tests
      - name: Test
        run: nx run-many --target=test --all

Docker

FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .

# Generate API clients
RUN nx run-many --target=generate-api --all

# Build the application
RUN nx build my-app --prod

FROM nginx:alpine
COPY --from=builder /app/dist/apps/my-app /usr/share/nginx/html

Troubleshooting Examples

Debug Generation Issues

Use dry run to test configuration without generating files:

{
  "targets": {
    "debug-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/swagger.json",
        "outputPath": "libs/api-client/src",
        "dryRun": true,
        "logToStderr": true
      }
    }
  }
}

Handle Large APIs

For large OpenAPI specifications, optimize generation:

{
  "targets": {
    "generate-api": {
      "executor": "@lambda-solutions/nx-plugin-openapi:generate-api",
      "options": {
        "inputSpec": "apps/demo/large-api.json",
        "outputPath": "libs/api-client/src",
        "skipValidateSpec": true,
        "minimalUpdate": true,
        "skipOperationExample": true
      }
    }
  }
}

Next Steps

Learn about Nx Integration for advanced workspace setup
API Reference for complete option details
Configuration Guide for detailed option explanations