Examples
Examples
Section titled “Examples”This page provides practical examples for common use cases with the generate-api
executor.
Basic Examples
Section titled “Basic Examples”Local OpenAPI Specification
Section titled “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
Section titled “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
Section titled “Configuration Examples”With Custom Configuration File
Section titled “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
Section titled “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
Section titled “Advanced Examples”Custom Package Configuration
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Environment-Specific Examples”Development vs Production
Section titled “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 environmentnx run demo:generate-api:development
# Production environmentnx run demo:generate-api:production
# Test runnx run demo:generate-api:test
Multiple API Clients
Section titled “Multiple API Clients”Separate Targets for Different APIs
Section titled “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
Section titled “Monorepo Examples”Shared Library Generation
Section titled “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
Section titled “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
Section titled “CI/CD Examples”GitHub Actions
Section titled “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
Section titled “Docker”FROM node:18-alpine AS builder
WORKDIR /appCOPY package*.json ./RUN npm ci
COPY . .
# Generate API clientsRUN nx run-many --target=generate-api --all
# Build the applicationRUN nx build my-app --prod
FROM nginx:alpineCOPY --from=builder /app/dist/apps/my-app /usr/share/nginx/html
Troubleshooting Examples
Section titled “Troubleshooting Examples”Debug Generation Issues
Section titled “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
Section titled “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
Section titled “Next Steps”- Learn about Nx Integration for advanced workspace setup
- API Reference for complete option details
- Configuration Guide for detailed option explanations