openapi-codegen-orchestrator

name	openapi-codegen-orchestrator
description	Orchestrate multi-language SDK generation from OpenAPI specifications. Configure OpenAPI Generator per language, apply custom templates and post-processing, handle edge cases and custom extensions, and validate generated code compilation.
allowed-tools	Bash(*) Read Write Edit Glob Grep WebFetch
metadata	{"author":"babysitter-sdk","version":"1.0.0","category":"sdk-code-generation","backlog-id":"SK-SDK-001"}

openapi-codegen-orchestrator

You are openapi-codegen-orchestrator - a specialized skill for orchestrating multi-language SDK generation from OpenAPI specifications, enabling consistent, high-quality SDK production across diverse programming ecosystems.

Overview

This skill enables AI-powered SDK code generation including:

• Configuring OpenAPI Generator for multiple target languages
• Applying custom templates and post-processing transformations
• Handling edge cases and OpenAPI extensions
• Validating generated code compilation
• Managing generator versions and compatibility
• Customizing code style per language idioms
• Orchestrating parallel multi-language builds

Prerequisites

• Node.js 18+ or Java 11+
• OpenAPI Generator CLI (npm or jar)
• OpenAPI 3.x specification file
• Target language toolchains (npm, pip, maven, etc.)
• Docker (optional, for containerized generation)

Capabilities

1. OpenAPI Generator Configuration

Configure OpenAPI Generator for multiple languages:

# openapi-generator-config.yaml
generatorConfigs:
  typescript-axios:
    generatorName: typescript-axios
    output: ./sdks/typescript
    additionalProperties:
      npmName: "@company/api-client"
      npmVersion: "1.0.0"
      supportsES6: true
      withInterfaces: true
      withSeparateModelsAndApi: true
      modelPropertyNaming: camelCase
      enumPropertyNaming: UPPERCASE
    templateDir: ./templates/typescript
    globalProperties:
      skipFormModel: false

  python:
    generatorName: python
    output: ./sdks/python
    additionalProperties:
      packageName: company_api_client
      packageVersion: "1.0.0"
      projectName: company-api-client
      generateSourceCodeOnly: false
    templateDir: ./templates/python

  java:
    generatorName: java
    output: ./sdks/java
    additionalProperties:
      groupId: com.company.api
       
       
       
       
       
       
     

  
     
     
    
       
       
       
       

2. Multi-Language Generation Script

Orchestrate SDK generation across languages:

// generate-sdks.js
import { execSync } from 'child_process';
import { readFileSync, writeFileSync } from 'fs';
import yaml from 'yaml';

const config = yaml.parse(readFileSync('openapi-generator-config.yaml', 'utf8'));
const specPath = process.env.OPENAPI_SPEC || './openapi.yaml';

async function generateSDK(language, langConfig) {
  console.log(`Generating ${language} SDK...`);

  const args = [
    'generate',
    '-i', specPath,
    '-g', langConfig.generatorName,
    '-o', langConfig.output,
    '--skip-validate-spec'
  ];

  // Add additional properties
  if (langConfig.additionalProperties) {
    for (const [key, value] of Object.entries(langConfig.additionalProperties)) {
      args.push('--additional-properties', `${key}=${value}`);
    }
  }

  
   (langConfig.) {
    args.(, langConfig.);
  }

  
   (langConfig.) {
     ( [key, value]  .(langConfig.)) {
      args.(, );
    }
  }

   {
    (, {
      : 
    });
    .();
     { language, :  };
  }  (error) {
    .(, error.);
     { language, : , : error. };
  }
}

  () {
   results = [];

   ( [language, langConfig]  .(config.)) {
     result =  (language, langConfig);
    results.(result);
  }

  .();
  results.( {
    .();
  });

   results;
}

();

3. Custom Template Management

Create and manage custom Mustache templates:

{{! templates/typescript/apiInner.mustache }}
{{#operations}}
{{#operation}}
/**
 * {{summary}}
 * {{notes}}
 {{#allParams}}
 * @param {{paramName}} {{description}}
 {{/allParams}}
 * @throws {ApiError} if the request fails
 */
public async {{operationId}}({{#allParams}}{{paramName}}{{^required}}?{{/required}}: {{{dataType}}}{{^-last}}, {{/-last}}{{/allParams}}): Promise<{{{returnType}}}{{^returnType}}void{{/returnType}}> {
  const response = await this.{{operationId}}Raw({{#allParams}}{{paramName}}{{^-last}}, {{/-last}}{{/allParams}});
  {{#returnType}}
  return await response.value();
  {{/returnType}}
}
{{/operation}}
{{/operations}}

4. Post-Generation Processing

Apply transformations after generation:

// post-process.js
import { glob } from 'glob';
import { readFileSync, writeFileSync } from 'fs';
import path from 'path';

const postProcessors = {
  typescript: async (outputDir) => {
    // Add ESLint disable comments for generated code
    const files = await glob(`${outputDir}/**/*.ts`);

    for (const file of files) {
      let content = readFileSync(file, 'utf8');

      // Add header comment
      if (!content.startsWith('/* eslint-disable */')) {
        content = `/* eslint-disable */\n/**\n * Auto-generated by OpenAPI Generator\n * Do not edit manually\n */\n\n${content}`;
      }

      // Fix common issues
      content = content
        .replace(/any\[\]/g, 'unknown[]')  // Replace any[] with unknown[]
        .replace(/: any;/g, ': unknown;'); // Replace any with unknown

      writeFileSync(file, content);
    }

    // Generate barrel exports
    const models = await glob(`/models/*.ts`);
      = models
      .( path.(f, ))
      .( n !== )
      .( )
      .();

    (,  + );
  },

  :  (outputDir) => {
    
     files =  ();

     ( file  files) {
       content = (file, );

      
       (!content.()) {
        content = ;
      }

      (file, content);
    }
  },

  :  (outputDir) => {
    
     files =  ();

     ( file  files) {
       content = (file, );

      
       (!content.()) {
        content = content.(
          ,
          
        );
      }

      (file, content);
    }
  }
};

  () {
   (postProcessors[language]) {
    .();
     postProcessors[language](outputDir);
    .();
  }
}

5. Generated Code Validation

Validate generated SDKs compile and pass linting:

// validate-sdks.js
import { execSync } from 'child_process';

const validators = {
  'typescript-axios': {
    install: 'npm install',
    build: 'npm run build',
    lint: 'npm run lint',
    test: 'npm test'
  },
  python: {
    install: 'pip install -e .[dev]',
    build: 'python -m build',
    lint: 'ruff check .',
    test: 'pytest'
  },
  java: {
    install: 'mvn install -DskipTests',
    build: 'mvn compile',
    lint: 'mvn checkstyle:check',
    test: 'mvn test'
  },
  go: {
    install: 'go mod download',
    build: 'go build ./...',
    lint: 'golangci-lint run',
    test: 'go test ./...'
  }
};

async function validateSDK(language, outputDir) {
  const steps = validators[language];
  if (!steps) {
    console.log(`No validator for ${language}`);
     { language, :  };
  }

   results = { language, : {} };

   ( [step, command]  .(steps)) {
     {
      .();
      (command, { : outputDir, :  });
      results.[step] = ;
    }  (error) {
      .(, error.);
      results.[step] = ;
      results. = ;
      ;
    }
  }

  results. = results. || ;
   results;
}

6. OpenAPI Extension Handling

Handle custom OpenAPI extensions:

// extension-handler.js
const extensionHandlers = {
  'x-sdk-operation-group': (operation, value) => {
    // Group operations into namespaced clients
    operation.operationGroup = value;
  },

  'x-sdk-ignore': (operation, value) => {
    // Skip generation for this operation
    operation.vendorExtensions['x-skip-generation'] = value;
  },

  'x-sdk-paginated': (operation, value) => {
    // Generate pagination helpers
    operation.vendorExtensions['x-pagination'] = {
      enabled: true,
      pageParam: value.pageParam || 'page',
      limitParam: value.limitParam || 'limit',
      resultPath: value.resultPath || 'data'
    };
  },

  'x-sdk-deprecated-date': (operation, value) => {
    // Add deprecation with sunset date
    operation.vendorExtensions['x-deprecation'] = {
      date: value,
      message: `This operation will be removed after ${value}`
    };
  }
};

function processExtensions(spec) {
  // Process path-level extensions
  for (const [path, pathItem]  .(spec.)) {
     ( [method, operation]  .(pathItem)) {
       ( operation !== ) ;

       ( [ext, value]  .(operation)) {
         (ext.() && extensionHandlers[ext]) {
          extensionHandlers[ext](operation, value);
        }
      }
    }
  }

   spec;
}

7. CI/CD Integration

GitHub Actions workflow for SDK generation:

name: Generate SDKs

on:
  push:
    paths:
      - 'openapi.yaml'
      - 'templates/**'
  workflow_dispatch:
    inputs:
      languages:
        description: 'Languages to generate (comma-separated or "all")'
        default: 'all'

jobs:
  generate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        language: [typescript, python, java, go]

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup language toolchain
        uses: ./.github/actions/setup-${{ matrix.language }}

      - name: Install OpenAPI Generator
            

         
         
         
             

         
             

          
         
        
             
             

  
     
     
       
    
          
         

         
         

8. Configuration Schema

Validate generator configuration:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "generatorConfigs": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "required": ["generatorName", "output"],
        "properties": {
          "generatorName": {
            "type": "string",
            "enum": ["typescript-axios", "typescript-fetch", "python", "java", "go",  
          
              
              
              
              
        
      
    
  

MCP Server Integration

This skill can leverage the following MCP servers for enhanced capabilities:

Server	Description	Installation
mcp-openapi-schema	Explore OpenAPI schemas	GitHub
openapi-mcp-server	Navigate complex OpenAPIs	GitHub
swagger-mcp	Analyze OpenAPI specifications	GitHub

Best Practices

1. Version control templates - Track custom templates in git
2. Validate specs first - Run spec linting before generation
3. Use semantic versioning - Version SDKs with semver
4. Automate everything - CI/CD for generation and publishing
5. Test generated code - Include tests in validation
6. Document customizations - Explain template changes
7. Handle deprecations - Process deprecation extensions
8. Monitor generation - Track generation metrics

Process Integration

This skill integrates with the following processes:

• sdk-code-generation-pipeline.js - Main generation workflow
• multi-language-sdk-strategy.js - Language-specific configurations
• api-design-specification.js - Spec preparation
• package-distribution.js - SDK publishing

Output Format

When executing operations, provide structured output:

{
  "operation": "generate",
  "specPath": "./openapi.yaml",
  "specVersion": "3.0.3",
  "generatedSDKs": [
    {
      "language": "typescript",
      "generator": "typescript-axios",
      "outputPath": "./sdks/typescript",
      "status": "success",
      "validation": {
        "compile": "passed",
        "lint": "passed",
        "test": "passed"
      },
      "files": 42,
      "models": 15,
       
    
  
   
   

Error Handling

• Validate OpenAPI spec before generation
• Handle unsupported features gracefully
• Provide clear error messages for template issues
• Support retry for transient failures
• Log detailed diagnostics for debugging

Constraints

• OpenAPI Generator version compatibility varies by generator
• Custom templates require maintenance across versions
• Some generators have limited feature support
• Large specs may require memory tuning
• Generated code style may need post-processing