feat: add open api spec type generation

Author: owinter86

.gitignore

@@ -0,0 +1,37 @@
+# Build output
+dist/
+test/generated/
+
+# Dependencies
+node_modules/
+
+# IDE files
+.vscode/
+.idea/
+*.sublime-*
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Test coverage
+coverage/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# npm package files
+package-lock.json
+yarn.lock 

example-config.json

@@ -0,0 +1,8 @@
+{
+  "specSource": "https://api.example.com/swagger.json",
+  "exportDir": "./generated",
+  "options": {
+    "generateMocks": true,
+    "includeJSDocs": true
+  }
+} 

package.json

@@ -0,0 +1,23 @@
+{
+  "name": "openapi-axios-generator",
+  "version": "1.0.0",
+  "description": "Generate Axios API clients from OpenAPI specifications",
+  "main": "dist/index.js",
+  "bin": {
+    "generate-api": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "test": "tsc -p test/tsconfig.json && node dist/test/index.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "openapi-types": "^12.1.3",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.0",
+    "typescript": "^5.2.2"
+  }
+} 

src/cli.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import { resolve } from 'path';
+import { loadConfig } from './config/loadConfig';
+import { generateApiClient } from './generator/apiGenerator';
+
+async function main() {
+  try {
+    const configPath = process.argv[2];
+    
+    if (!configPath) {
+      console.error('Please provide a path to your configuration file');
+      process.exit(1);
+    }
+    
+    const resolvedConfigPath = resolve(process.cwd(), configPath);
+    const config = await loadConfig(resolvedConfigPath);
+    
+    await generateApiClient(config);
+    
+    console.log('API client generated successfully!');
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Error:', error.message);
+    } else {
+      console.error('Error: Unknown error occurred');
+    }
+    process.exit(1);
+  }
+}
+
+main(); 

src/config/loadConfig.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'fs/promises';
+import { OpenAPIConfig } from '../types/config';
+
+export async function loadConfig(configPath: string): Promise<OpenAPIConfig> {
+  try {
+    const configContent = await readFile(configPath, 'utf-8');
+    const config = JSON.parse(configContent) as OpenAPIConfig;
+    
+    // Validate required fields
+    if (!config.specSource) {
+      throw new Error('specSource is required in configuration');
+    }
+    
+    if (!config.exportDir) {
+      throw new Error('exportDir is required in configuration');
+    }
+    
+    // Set default options
+    config.options = {
+      generateMocks: true,
+      includeJSDocs: true,
+      ...config.options
+    };
+    
+    return config;
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to load configuration: ${error.message}`);
+    }
+    throw new Error('Failed to load configuration: Unknown error');
+  }
+} 

src/generator/apiGenerator.ts

@@ -0,0 +1,64 @@
+import { OpenAPIConfig } from '../types/config';
+import { readFile, mkdir, writeFile } from 'fs/promises';
+import { resolve } from 'path';
+import axios from 'axios';
+import * as yaml from 'yaml';
+import { OpenAPIV3 } from 'openapi-types';
+import { generateTypeDefinitions } from './schemaGenerator';
+
+/**
+ * Loads the OpenAPI specification from either a URL or local file
+ */
+async function loadOpenAPISpec(specSource: string): Promise<OpenAPIV3.Document> {
+  try {
+    if (specSource.startsWith('http')) {
+      const response = await axios.get(specSource);
+      return response.data;
+    } else {
+      const content = await readFile(specSource, 'utf-8');
+      // Handle both JSON and YAML formats
+      return specSource.endsWith('.json') 
+        ? JSON.parse(content)
+        : yaml.parse(content);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to load OpenAPI spec: ${error.message}`);
+    }
+    throw new Error('Failed to load OpenAPI spec: Unknown error');
+  }
+}
+
+/**
+ * Main function to generate the API client
+ */
+export async function generateApiClient(config: OpenAPIConfig): Promise<void> {
+  try {
+    // Load the OpenAPI specification
+    const spec = await loadOpenAPISpec(config.specSource);
+    
+    // Create export directory if it doesn't exist
+    await mkdir(config.exportDir, { recursive: true });
+    
+    // Generate and write type definitions
+    const typeDefinitions = generateTypeDefinitions(spec);
+    await writeFile(
+      resolve(config.exportDir, 'types.ts'),
+      typeDefinitions,
+      'utf-8'
+    );
+    
+    console.log('Generated TypeScript interfaces successfully');
+    
+    // TODO: Implement remaining steps
+    // 1. Generate Axios client methods for each path
+    // 2. Generate mock data if enabled
+    // 3. Add JSDoc comments if enabled
+    
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to generate API client: ${error.message}`);
+    }
+    throw new Error('Failed to generate API client: Unknown error');
+  }
+} 

src/generator/schemaGenerator.ts

@@ -0,0 +1,127 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+interface SchemaContext {
+  schemas: { [key: string]: OpenAPIV3.SchemaObject };
+  generatedTypes: Set<string>;
+}
+
+/**
+ * Converts OpenAPI schema type to TypeScript type
+ */
+function getTypeFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, context: SchemaContext): string {
+  if (!schema) return 'any';
+
+  if ('$ref' in schema) {
+    const refType = schema.$ref.split('/').pop()!;
+    return refType;
+  }
+
+  // Handle enum types properly
+  if (schema.enum) {
+    return schema.enum.map(e => typeof e === 'string' ? `'${e}'` : e).join(' | ');
+  }
+
+  switch (schema.type) {
+    case 'string':
+      return 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      const itemType = getTypeFromSchema(schema.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, context);
+      return `Array<${itemType}>`;
+    case 'object':
+      if (schema.properties) {
+        const properties = Object.entries(schema.properties)
+          .map(([key, prop]) => {
+            const isRequired = schema.required?.includes(key);
+            const propertyType = getTypeFromSchema(prop as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, context);
+            return `  ${key}${isRequired ? '' : '?'}: ${propertyType};`;
+          })
+          .join('\n');
+        return `{\n${properties}\n}`;
+      }
+      if (schema.additionalProperties) {
+        const valueType = typeof schema.additionalProperties === 'boolean' 
+          ? 'any' 
+          : getTypeFromSchema(schema.additionalProperties as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, context);
+        return `Record<string, ${valueType}>`;
+      }
+      return 'Record<string, any>';
+    default:
+      return 'any';
+  }
+}
+
+function generateTypeDefinition(name: string, schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, context: SchemaContext): string {
+  const description = !('$ref' in schema) && schema.description 
+    ? `/**\n * ${schema.description}\n */\n`
+    : '';
+
+  const typeValue = getTypeFromSchema(schema, context);
+  
+  // Use 'type' for primitives, unions, and simple types
+  // Use 'interface' only for complex objects with properties
+  const isInterface = !('$ref' in schema) && schema.type === 'object' && schema.properties;
+  
+  return isInterface
+    ? `${description}export interface ${name} ${typeValue}\n\n`
+    : `${description}export type ${name} = ${typeValue}\n\n`;
+}
+
+/**
+ * Generates TypeScript interface definitions from OpenAPI schemas
+ */
+export function generateTypeDefinitions(spec: OpenAPIV3.Document): string {
+  const context: SchemaContext = {
+    schemas: spec.components?.schemas as { [key: string]: OpenAPIV3.SchemaObject } || {},
+    generatedTypes: new Set()
+  };
+
+  let output = '/* Generated TypeScript Definitions */\n\n';
+
+  // Generate types for all schema definitions
+  for (const [name, schema] of Object.entries(context.schemas)) {
+    if (context.generatedTypes.has(name)) continue;
+    output += generateTypeDefinition(name, schema, context);
+    context.generatedTypes.add(name);
+  }
+
+  // Generate request/response types
+  if (spec.paths) {
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+      for (const [method, operation] of Object.entries(pathItem as OpenAPIV3.PathItemObject)) {
+        if (method === '$ref') continue;
+
+        const operationObject = operation as OpenAPIV3.OperationObject;
+        if (!operationObject) continue;
+
+        // Generate request body type
+        if (operationObject.requestBody) {
+          const content = (operationObject.requestBody as OpenAPIV3.RequestBodyObject).content;
+          const jsonContent = content['application/json'];
+          if (jsonContent?.schema) {
+            const typeName = `${operationObject.operationId}Request`;
+            output += generateTypeDefinition(typeName, jsonContent.schema as OpenAPIV3.SchemaObject, context);
+          }
+        }
+
+        // Generate response types
+        if (operationObject.responses) {
+          for (const [code, response] of Object.entries(operationObject.responses)) {
+            const responseObj = response as OpenAPIV3.ResponseObject;
+            const content = responseObj.content?.['application/json'];
+            if (content?.schema) {
+              const typeName = `${operationObject.operationId}Response${code}`;
+              output += generateTypeDefinition(typeName, content.schema as OpenAPIV3.SchemaObject, context);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return output;
+} 

src/types/config.ts

@@ -0,0 +1,29 @@
+export interface OpenAPIConfig {
+  /**
+   * OpenAPI specification source - can be a URL or local file path
+   * Supports JSON, YAML, or YML formats
+   */
+  specSource: string;
+  
+  /**
+   * Directory where generated files will be exported
+   */
+  exportDir: string;
+  
+  /**
+   * Optional configuration options
+   */
+  options?: {
+    /**
+     * Generate mock data for API responses
+     * @default true
+     */
+    generateMocks?: boolean;
+    
+    /**
+     * Include JSDoc comments in generated code
+     * @default true
+     */
+    includeJSDocs?: boolean;
+  };
+} 

test/configs/test-config.json

@@ -0,0 +1,8 @@
+{
+  "specSource": "https://api.jaarbeurs.acc.lightbase.nl/_compas/structure.json?format=openapi",
+  "exportDir": "./test/generated",
+  "options": {
+    "generateMocks": true,
+    "includeJSDocs": true
+  }
+}