@g1cloud/api-gen 1.0.0

package/src/generator/openapiGenerator.ts

@@ -0,0 +1,378 @@
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import {
+  CLIOptions,
+  OpenAPISpec,
+  ControllerInfo,
+  EndpointInfo,
+  ProcessingContext,
+  PathItem,
+  OperationObject,
+  ParameterObject,
+  RequestBodyObject,
+  ResponseObject,
+  SchemaInfo,
+  TagInfo,
+} from '../types';
+import { generateSchemas } from '../analyzer/schemaGenerator';
+
+/**
+ * Generate OpenAPI YAML from analyzed controllers
+ */
+export function generateOpenAPISpec(
+  controllers: ControllerInfo[],
+  context: ProcessingContext,
+  options: CLIOptions
+): OpenAPISpec {
+  // Generate schemas for all referenced types
+  const schemas = generateSchemas(context);
+
+  // Build tags from controllers
+  const tags: TagInfo[] = controllers.map(controller => ({
+    name: controller.className,
+    description: controller.javaClass.javadoc || `Endpoints for ${controller.className}`,
+  }));
+
+  // Build paths
+  const paths: Record<string, PathItem> = {};
+
+  for (const controller of controllers) {
+    for (const endpoint of controller.endpoints) {
+      const path = endpoint.path;
+
+      if (!paths[path]) {
+        paths[path] = {};
+      }
+
+      paths[path][endpoint.method] = buildOperation(endpoint, controller.className);
+    }
+  }
+
+  // Convert schema Map to object
+  const schemaObject: Record<string, SchemaInfo> = {};
+  for (const [name, schema] of schemas) {
+    schemaObject[name] = schema;
+  }
+
+  // Build the spec
+  const spec: OpenAPISpec = {
+    openapi: '3.0.0',
+    info: {
+      title: options.title,
+      version: options.version,
+    },
+    tags,
+    paths,
+    components: {
+      schemas: schemaObject,
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+        },
+      },
+    },
+  };
+
+  // Add servers if base path is specified
+  if (options.basePath) {
+    spec.servers = [{ url: `http://localhost:8080${options.basePath}` }];
+  }
+
+  return spec;
+}
+
+/**
+ * Build operation object for an endpoint
+ */
+function buildOperation(endpoint: EndpointInfo, controllerName?: string): OperationObject {
+  const operation: OperationObject = {
+    summary: endpoint.summary,
+    operationId: endpoint.operationId,
+    responses: {},
+  };
+
+  // Add tag for controller grouping
+  if (controllerName) {
+    operation.tags = [controllerName];
+  }
+
+  // Build description with javadoc, @return, and security info
+  const descriptionParts: string[] = [];
+
+  if (endpoint.description) {
+    descriptionParts.push(endpoint.description);
+  }
+
+  // Add @return description from javadoc
+  if (endpoint.returnDescription) {
+    descriptionParts.push(`\n\n**Returns:** ${endpoint.returnDescription}`);
+  }
+
+  // Add security info to description
+  if (endpoint.security.roles.length > 0) {
+    descriptionParts.push(`\n\n**Required Roles:** ${endpoint.security.roles.join(', ')}`);
+  }
+
+  if (endpoint.security.securityExpression) {
+    descriptionParts.push(`\n\n**Security Expression:** \`${endpoint.security.securityExpression}\``);
+  }
+
+  if (descriptionParts.length > 0) {
+    operation.description = descriptionParts.join('');
+  }
+
+  // Add parameters
+  if (endpoint.parameters.length > 0) {
+    operation.parameters = endpoint.parameters.map(buildParameter);
+  }
+
+  // Add request body
+  if (endpoint.requestBody) {
+    operation.requestBody = buildRequestBody(endpoint.requestBody);
+  }
+
+  // Add responses
+  for (const response of endpoint.responses) {
+    operation.responses[response.statusCode] = buildResponse(response);
+  }
+
+  // Add security
+  if (endpoint.security.roles.length > 0 || endpoint.security.authorities.length > 0) {
+    operation.security = [{ bearerAuth: [] }];
+  }
+
+  // Add x-required-roles
+  if (endpoint.security.roles.length > 0) {
+    operation['x-required-roles'] = endpoint.security.roles;
+  }
+
+  // Add x-security-expression for complex expressions
+  if (endpoint.security.hasComplexExpression && endpoint.security.securityExpression) {
+    operation['x-security-expression'] = endpoint.security.securityExpression;
+  }
+
+  return operation;
+}
+
+/**
+ * Build parameter object
+ */
+function buildParameter(param: import('../types').ParameterInfo): ParameterObject {
+  const parameter: ParameterObject = {
+    name: param.name,
+    in: param.in,
+    schema: param.schema || { type: param.type },
+  };
+
+  if (param.required) {
+    parameter.required = true;
+  }
+
+  if (param.description) {
+    parameter.description = param.description;
+  }
+
+  return parameter;
+}
+
+/**
+ * Build request body object
+ */
+function buildRequestBody(requestBody: import('../types').RequestBodyInfo): RequestBodyObject {
+  const body: RequestBodyObject = {
+    required: requestBody.required,
+    content: {
+      [requestBody.contentType]: {
+        schema: requestBody.schema,
+      },
+    },
+  };
+
+  // Add description from @param javadoc if available
+  if (requestBody.description) {
+    body.description = requestBody.description;
+  }
+
+  return body;
+}
+
+/**
+ * Build response object
+ */
+function buildResponse(response: import('../types').ResponseInfo): ResponseObject {
+  const responseObj: ResponseObject = {
+    description: response.description,
+  };
+
+  // Add headers
+  if (response.headers) {
+    responseObj.headers = {};
+    for (const [name, header] of Object.entries(response.headers)) {
+      responseObj.headers[name] = {
+        schema: header.schema,
+        description: header.description,
+      };
+    }
+  }
+
+  // Add content
+  if (response.contentType && response.schema) {
+    responseObj.content = {
+      [response.contentType]: {
+        schema: response.schema,
+      },
+    };
+  }
+
+  return responseObj;
+}
+
+/**
+ * Recursively extract all $ref types from a schema
+ */
+function extractRefsFromSchema(schema: any, refs: Set<string>): void {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  // Direct $ref
+  if (schema.$ref && typeof schema.$ref === 'string') {
+    const typeName = schema.$ref.replace('#/components/schemas/', '');
+    refs.add(typeName);
+  }
+
+  // Array items
+  if (schema.items) {
+    extractRefsFromSchema(schema.items, refs);
+  }
+
+  // Object properties
+  if (schema.properties) {
+    for (const prop of Object.values(schema.properties)) {
+      extractRefsFromSchema(prop, refs);
+    }
+  }
+
+  // additionalProperties
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+    extractRefsFromSchema(schema.additionalProperties, refs);
+  }
+
+  // allOf, anyOf, oneOf
+  for (const key of ['allOf', 'anyOf', 'oneOf']) {
+    if (Array.isArray(schema[key])) {
+      for (const subSchema of schema[key]) {
+        extractRefsFromSchema(subSchema, refs);
+      }
+    }
+  }
+}
+
+/**
+ * Generate OpenAPI spec for a single controller
+ */
+export function generateOpenAPISpecForController(
+  controller: ControllerInfo,
+  context: ProcessingContext,
+  options: CLIOptions
+): OpenAPISpec {
+  // Create a temporary context with only this controller to generate relevant schemas
+  const singleControllerContext: ProcessingContext = {
+    javaClasses: context.javaClasses,
+    controllers: [controller],
+    dtoSchemas: new Map(),
+    referencedTypes: new Set(),
+  };
+
+  // Collect referenced types from this controller's endpoints
+  for (const endpoint of controller.endpoints) {
+    // Extract refs from request body schema (including nested refs like array items)
+    if (endpoint.requestBody?.schema) {
+      extractRefsFromSchema(endpoint.requestBody.schema, singleControllerContext.referencedTypes);
+    }
+
+    // Extract refs from response schemas
+    for (const response of endpoint.responses) {
+      if (response.schema) {
+        extractRefsFromSchema(response.schema, singleControllerContext.referencedTypes);
+      }
+    }
+
+    // Extract refs from parameter schemas
+    for (const param of endpoint.parameters) {
+      if (param.schema) {
+        extractRefsFromSchema(param.schema, singleControllerContext.referencedTypes);
+      }
+    }
+  }
+
+  // Generate schemas for referenced types
+  const schemas = generateSchemas(singleControllerContext);
+
+  // Build paths for this controller only
+  const paths: Record<string, PathItem> = {};
+  for (const endpoint of controller.endpoints) {
+    const path = endpoint.path;
+    if (!paths[path]) {
+      paths[path] = {};
+    }
+    paths[path][endpoint.method] = buildOperation(endpoint, controller.className);
+  }
+
+  // Build tag for this controller
+  const tags: TagInfo[] = [{
+    name: controller.className,
+    description: controller.javaClass.javadoc || `Endpoints for ${controller.className}`,
+  }];
+
+  // Convert schema Map to object
+  const schemaObject: Record<string, SchemaInfo> = {};
+  for (const [name, schema] of schemas) {
+    schemaObject[name] = schema;
+  }
+
+  // Build the spec with controller name as title
+  const spec: OpenAPISpec = {
+    openapi: '3.0.0',
+    info: {
+      title: controller.className,
+      version: options.version,
+    },
+    tags,
+    paths,
+    components: {
+      schemas: schemaObject,
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+        },
+      },
+    },
+  };
+
+  // Add servers if base path is specified
+  if (options.basePath) {
+    spec.servers = [{ url: `http://localhost:8080${options.basePath}` }];
+  }
+
+  return spec;
+}
+
+/**
+ * Write OpenAPI spec to YAML file
+ */
+export function writeOpenAPISpec(spec: OpenAPISpec, outputPath: string): void {
+  const yamlContent = yaml.dump(spec, {
+    indent: 2,
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: false,
+  });
+
+  fs.writeFileSync(outputPath, yamlContent, 'utf-8');
+  console.log(`  Written: ${outputPath}`);
+}

package/src/index.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { CLIOptions, ProcessingContext } from './types';
+import { parseJavaSource } from './parser/javaParser';
+import { analyzeControllers } from './analyzer/controllerAnalyzer';
+import { generateOpenAPISpec, generateOpenAPISpecForController, writeOpenAPISpec } from './generator/openapiGenerator';
+
+const program = new Command();
+
+// Helper to collect multiple values for an option
+function collect(value: string, previous: string[]): string[] {
+  return previous.concat([value]);
+}
+
+program
+  .name('spring-to-openapi')
+  .description('Generate OpenAPI v3 YAML from Spring Boot Java source code')
+  .version('1.0.0')
+  .requiredOption('-s, --source <path...>', 'Java source code directory path(s) (can be specified multiple times)', collect, [])
+  .option('-a, --api-source <path>', 'Directory to search for RestControllers (defaults to first --source)')
+  .option('-o, --output <path>', 'Output YAML file path (generates single combined file)')
+  .option('-d, --out-dir <path>', 'Output directory path (generates separate YAML per controller)')
+  .option('-t, --title <title>', 'API title', 'API Documentation')
+  .option('--api-version <version>', 'API version', '1.0.0')
+  .option('-b, --base-path <path>', 'API base path')
+  .action(async (options: any) => {
+    try {
+      await run(options);
+    } catch (error) {
+      console.error('Error:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+async function run(options: any): Promise<void> {
+  const startTime = Date.now();
+
+  // Validate output options
+  if (!options.output && !options.outDir) {
+    options.output = 'openapi.yaml'; // default to single file
+  }
+
+  if (options.output && options.outDir) {
+    console.error('Error: Cannot use both --output and --out-dir. Choose one output mode.');
+    process.exit(1);
+  }
+
+  // Normalize source to array
+  const sources: string[] = Array.isArray(options.source) ? options.source : [options.source];
+
+  if (sources.length === 0) {
+    console.error('Error: At least one --source path is required.');
+    process.exit(1);
+  }
+
+  // Normalize options
+  const cliOptions: CLIOptions = {
+    source: sources,
+    apiSource: options.apiSource,  // Optional: specific directory for RestController search
+    output: options.output,
+    outDir: options.outDir,
+    title: options.title,
+    version: options.apiVersion,
+    basePath: options.basePath,
+  };
+
+  const isDirectoryMode = !!cliOptions.outDir;
+
+  console.log('='.repeat(60));
+  console.log('Spring Boot to OpenAPI Generator');
+  console.log('='.repeat(60));
+  if (cliOptions.source.length === 1) {
+    console.log(`\nSource directory: ${cliOptions.source[0]}`);
+  } else {
+    console.log(`\nSource directories:`);
+    for (const src of cliOptions.source) {
+      console.log(`  - ${src}`);
+    }
+  }
+  if (cliOptions.apiSource) {
+    console.log(`API source directory: ${cliOptions.apiSource} (RestController search)`);
+  }
+  if (isDirectoryMode) {
+    console.log(`Output directory: ${cliOptions.outDir} (per-controller mode)`);
+  } else {
+    console.log(`Output file: ${cliOptions.output}`);
+  }
+  console.log(`API title: ${cliOptions.title}`);
+  console.log(`API version: ${cliOptions.version}`);
+  if (cliOptions.basePath) {
+    console.log(`Base path: ${cliOptions.basePath}`);
+  }
+  console.log();
+
+  // Resolve paths
+  const sourcePaths = cliOptions.source.map(s => path.resolve(s));
+  const apiSourcePath = cliOptions.apiSource ? path.resolve(cliOptions.apiSource) : undefined;
+
+  // Step 1: Parse Java files from all source directories
+  console.log('Step 1: Parsing Java source files...');
+  const javaClasses = new Map<string, any>();
+
+  for (const sourcePath of sourcePaths) {
+    const classes = await parseJavaSource(sourcePath);
+    console.log(`  Found ${classes.size} class(es) in ${sourcePath}`);
+    // Merge classes (later sources override earlier ones for same class name)
+    for (const [name, cls] of classes) {
+      javaClasses.set(name, cls);
+    }
+  }
+  console.log(`  Total: ${javaClasses.size} Java class(es)`);
+
+  if (javaClasses.size === 0) {
+    console.warn('Warning: No Java files found in the specified directory.');
+    return;
+  }
+
+  // Step 2: Initialize processing context
+  const context: ProcessingContext = {
+    javaClasses,
+    controllers: [],
+    dtoSchemas: new Map(),
+    referencedTypes: new Set(),
+    apiSourcePath,  // Pass apiSourcePath to filter RestControllers
+  };
+
+  // Step 3: Analyze controllers
+  console.log('\nStep 2: Analyzing REST controllers...');
+  const controllers = analyzeControllers(context);
+  context.controllers = controllers;
+
+  const totalEndpoints = controllers.reduce((sum, c) => sum + c.endpoints.length, 0);
+  console.log(`\n  Found ${controllers.length} controller(s) with ${totalEndpoints} endpoint(s)`);
+
+  if (controllers.length === 0) {
+    console.warn('Warning: No REST controllers found in the source files.');
+    return;
+  }
+
+  // Step 4: Generate and write OpenAPI spec(s)
+  console.log('\nStep 3: Generating OpenAPI specification...');
+
+  if (isDirectoryMode) {
+    // Directory mode: generate separate YAML file per controller
+    const outDirPath = path.resolve(cliOptions.outDir!);
+
+    // Create output directory if it doesn't exist
+    if (!fs.existsSync(outDirPath)) {
+      fs.mkdirSync(outDirPath, { recursive: true });
+    }
+
+    console.log('\nStep 4: Writing YAML files (per controller)...');
+    let totalSchemas = 0;
+
+    for (const controller of controllers) {
+      const spec = generateOpenAPISpecForController(controller, context, cliOptions);
+      const fileName = `${controller.className}.yaml`;
+      const outputPath = path.join(outDirPath, fileName);
+      writeOpenAPISpec(spec, outputPath);
+      totalSchemas += Object.keys(spec.components.schemas).length;
+    }
+
+    const endTime = Date.now();
+    console.log(`\nCompleted in ${endTime - startTime}ms`);
+    console.log('='.repeat(60));
+
+    // Print summary
+    console.log('\nSummary:');
+    console.log(`  Controllers: ${controllers.length}`);
+    console.log(`  Endpoints: ${totalEndpoints}`);
+    console.log(`  Files generated: ${controllers.length}`);
+
+    // Print generated files
+    console.log('\nGenerated files:');
+    for (const controller of controllers) {
+      const endpointCount = controller.endpoints.length;
+      console.log(`  ${controller.className}.yaml (${endpointCount} endpoint${endpointCount !== 1 ? 's' : ''})`);
+    }
+  } else {
+    // Single file mode: generate combined YAML
+    const spec = generateOpenAPISpec(controllers, context, cliOptions);
+    const outputPath = path.resolve(cliOptions.output!);
+
+    console.log('\nStep 4: Writing YAML output...');
+    writeOpenAPISpec(spec, outputPath);
+
+    const endTime = Date.now();
+    console.log(`\nCompleted in ${endTime - startTime}ms`);
+    console.log('='.repeat(60));
+
+    // Print summary
+    console.log('\nSummary:');
+    console.log(`  Controllers: ${controllers.length}`);
+    console.log(`  Endpoints: ${totalEndpoints}`);
+    console.log(`  Schemas: ${Object.keys(spec.components.schemas).length}`);
+
+    // Print endpoints by path
+    console.log('\nEndpoints:');
+    const paths = Object.keys(spec.paths).sort();
+    for (const p of paths) {
+      const methods = Object.keys(spec.paths[p]).sort();
+      for (const method of methods) {
+        console.log(`  ${method.toUpperCase().padEnd(7)} ${p}`);
+      }
+    }
+  }
+}
+
+program.parse();