@g1cloud/api-gen 1.0.0

package/src/analyzer/parameterAnalyzer.ts

@@ -0,0 +1,259 @@
+import {
+  JavaMethod,
+  JavaParameter,
+  JavaAnnotation,
+  ParameterInfo,
+  RequestBodyInfo,
+  ProcessingContext,
+  SchemaInfo,
+} from '../types';
+import { ASTAnalyzer } from '../parser/astAnalyzer';
+
+interface ParameterAnalysisResult {
+  parameters: ParameterInfo[];
+  requestBody?: RequestBodyInfo;
+  hasSearchParam: boolean;
+}
+
+/**
+ * Analyze method parameters and extract OpenAPI parameter/request body info
+ * @param method The Java method to analyze
+ * @param context Processing context
+ * @param paramDescriptions Javadoc @param descriptions (param name -> description)
+ */
+export function analyzeParameters(
+  method: JavaMethod,
+  context: ProcessingContext,
+  paramDescriptions: Record<string, string> = {}
+): ParameterAnalysisResult {
+  const parameters: ParameterInfo[] = [];
+  let requestBody: RequestBodyInfo | undefined;
+  let hasSearchParam = false;
+
+  for (const param of method.parameters) {
+    // Check if it's a SearchParam
+    if (ASTAnalyzer.isSearchParam(param.type)) {
+      hasSearchParam = true;
+      // Add SearchParam query parameters
+      parameters.push(...getSearchParamParameters());
+      continue;
+    }
+
+    // Get parameter type from annotations
+    const paramType = ASTAnalyzer.getParameterType(param.annotations);
+
+    // Get @param description from javadoc
+    const javadocDescription = paramDescriptions[param.name];
+
+    if (paramType === 'body') {
+      requestBody = createRequestBody(param, context, javadocDescription);
+    } else if (paramType) {
+      const paramInfo = createParameterInfo(param, paramType, javadocDescription);
+      if (paramInfo) {
+        parameters.push(paramInfo);
+      }
+    }
+    // Parameters without REST annotations are typically handled by Spring automatically
+    // but we skip them as they're not part of the API contract
+  }
+
+  return { parameters, requestBody, hasSearchParam };
+}
+
+/**
+ * Get SearchParam query parameters
+ */
+function getSearchParamParameters(): ParameterInfo[] {
+  return [
+    {
+      name: 'offset',
+      in: 'query',
+      required: false,
+      type: 'integer',
+      description: 'Pagination offset',
+      schema: { type: 'integer' },
+    },
+    {
+      name: 'limit',
+      in: 'query',
+      required: false,
+      type: 'integer',
+      description: 'Pagination limit',
+      schema: { type: 'integer' },
+    },
+    {
+      name: 'filter',
+      in: 'query',
+      required: false,
+      type: 'object',
+      description: 'Filter conditions',
+      schema: { $ref: '#/components/schemas/Filter' },
+    },
+    {
+      name: 'sort',
+      in: 'query',
+      required: false,
+      type: 'object',
+      description: 'Sort conditions',
+      schema: { $ref: '#/components/schemas/Sort' },
+    },
+  ];
+}
+
+/**
+ * Create ParameterInfo from a Java parameter
+ */
+function createParameterInfo(
+  param: JavaParameter,
+  paramType: 'query' | 'path' | 'header',
+  javadocDescription?: string
+): ParameterInfo | null {
+  // Find the relevant annotation
+  const annotation = param.annotations.find(
+    (a) => a.name === 'RequestParam' || a.name === 'PathVariable' || a.name === 'RequestHeader'
+  );
+
+  if (!annotation) {
+    return null;
+  }
+
+  // Get parameter name (from annotation or Java parameter name)
+  const paramName = getAnnotationStringValue(annotation, 'value') ||
+    getAnnotationStringValue(annotation, 'name') ||
+    param.name;
+
+  // Determine if required
+  let required = paramType === 'path'; // Path variables are always required
+  if (paramType !== 'path') {
+    const requiredValue = annotation.values['required'];
+    if (requiredValue !== undefined) {
+      required = requiredValue === 'true' || requiredValue === true;
+    } else {
+      // Default is true for @RequestParam
+      required = paramType === 'query';
+    }
+  }
+
+  // Get default value
+  const defaultValue = getAnnotationStringValue(annotation, 'defaultValue');
+  if (defaultValue) {
+    required = false; // If there's a default value, it's not required
+  }
+
+  // Convert Java type to OpenAPI type
+  const openApiType = ASTAnalyzer.javaTypeToOpenAPI(param.type);
+
+  return {
+    name: paramName,
+    in: paramType,
+    required,
+    type: openApiType.type,
+    description: javadocDescription,
+    defaultValue,
+    schema: {
+      type: openApiType.type,
+      format: openApiType.format,
+    },
+  };
+}
+
+/**
+ * Create RequestBodyInfo from a Java parameter
+ */
+function createRequestBody(
+  param: JavaParameter,
+  context: ProcessingContext,
+  javadocDescription?: string
+): RequestBodyInfo {
+  // Find @RequestBody annotation
+  const annotation = param.annotations.find((a) => a.name === 'RequestBody');
+
+  // Determine if required
+  let required = true;
+  if (annotation) {
+    const requiredValue = annotation.values['required'];
+    if (requiredValue !== undefined) {
+      required = requiredValue === 'true' || requiredValue === true;
+    }
+  }
+
+  // Create schema reference
+  const schema = createSchemaForType(param.type, param.genericType, context);
+
+  return {
+    required,
+    contentType: 'application/json',
+    schema,
+    description: javadocDescription,
+  };
+}
+
+/**
+ * Create a schema for a Java type
+ */
+export function createSchemaForType(
+  javaType: string,
+  genericType: string | undefined,
+  context: ProcessingContext
+): SchemaInfo {
+  // Check if it's a primitive or wrapper type
+  if (ASTAnalyzer.isPrimitiveOrWrapper(javaType)) {
+    return ASTAnalyzer.javaTypeToOpenAPI(javaType);
+  }
+
+  // Check if it's an array
+  if (javaType.endsWith('[]')) {
+    const elementType = javaType.slice(0, -2);
+    return {
+      type: 'array',
+      items: createSchemaForType(elementType, undefined, context),
+    };
+  }
+
+  // Check if it's a collection type
+  if (ASTAnalyzer.isCollectionType(javaType)) {
+    const itemType = genericType ? ASTAnalyzer.extractGenericType(genericType) : 'Object';
+    return {
+      type: 'array',
+      items: itemType ? createSchemaForType(itemType, undefined, context) : { type: 'object' },
+    };
+  }
+
+  // Check if it's a Map type
+  if (ASTAnalyzer.isMapType(javaType)) {
+    return {
+      type: 'object',
+      additionalProperties: true,
+    };
+  }
+
+  // Check if it's ResponseEntity - extract the generic type
+  if (ASTAnalyzer.isResponseEntity(javaType) && genericType) {
+    return createSchemaForType(genericType, undefined, context);
+  }
+
+  // It's a custom type (DTO) - add to referenced types and return a reference
+  const simpleName = javaType.split('.').pop() || javaType;
+  context.referencedTypes.add(simpleName);
+
+  return {
+    $ref: `#/components/schemas/${simpleName}`,
+  };
+}
+
+/**
+ * Get string value from annotation
+ */
+function getAnnotationStringValue(annotation: JavaAnnotation, key: string): string | undefined {
+  const value = annotation.values[key];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  return String(value);
+}

package/src/analyzer/responseAnalyzer.ts

@@ -0,0 +1,142 @@
+import {
+  JavaMethod,
+  ResponseInfo,
+  ProcessingContext,
+  HeaderInfo,
+  SchemaInfo,
+} from '../types';
+import { ASTAnalyzer } from '../parser/astAnalyzer';
+import { createSchemaForType } from './parameterAnalyzer';
+
+interface ResponseAnalysisResult {
+  responses: ResponseInfo[];
+  hasPaginatedList: boolean;
+  paginatedListItemType?: string;
+}
+
+/**
+ * Analyze method return type and extract response information
+ */
+export function analyzeResponse(
+  method: JavaMethod,
+  context: ProcessingContext
+): ResponseAnalysisResult {
+  const responses: ResponseInfo[] = [];
+  let hasPaginatedList = false;
+  let paginatedListItemType: string | undefined;
+
+  let returnType = method.returnType;
+  let genericType = method.returnGenericType;
+
+  // Handle ResponseEntity<T>
+  if (ASTAnalyzer.isResponseEntity(returnType)) {
+    // Extract the generic type from ResponseEntity
+    if (genericType) {
+      returnType = extractMainType(genericType);
+      genericType = extractNestedGenericType(genericType);
+    } else {
+      returnType = 'Object';
+    }
+  }
+
+  // Check for PaginatedList
+  if (ASTAnalyzer.isPaginatedList(returnType)) {
+    hasPaginatedList = true;
+    paginatedListItemType = genericType ? extractMainType(genericType) : undefined;
+
+    // Create PaginatedList response with headers
+    const response = createPaginatedListResponse(returnType, genericType, context);
+    responses.push(response);
+  } else if (returnType === 'void' || returnType === 'Void') {
+    // Void response
+    responses.push({
+      statusCode: '200',
+      description: 'Successful response',
+    });
+  } else {
+    // Regular response
+    const schema = createSchemaForType(returnType, genericType, context);
+    responses.push({
+      statusCode: '200',
+      description: 'Successful response',
+      contentType: 'application/json',
+      schema,
+    });
+  }
+
+  return { responses, hasPaginatedList, paginatedListItemType };
+}
+
+/**
+ * Create response for PaginatedList type
+ * PaginatedList<T> is treated as an array of T, with pagination info in headers
+ */
+function createPaginatedListResponse(
+  returnType: string,
+  genericType: string | undefined,
+  context: ProcessingContext
+): ResponseInfo {
+  const itemType = genericType ? extractMainType(genericType) : 'Object';
+
+  // Add the item type to referenced types
+  if (itemType !== 'Object' && !ASTAnalyzer.isPrimitiveOrWrapper(itemType)) {
+    context.referencedTypes.add(itemType);
+  }
+
+  // Create array schema directly (treat PaginatedList<T> as List<T>)
+  const arraySchema: SchemaInfo = {
+    type: 'array',
+    items: itemType !== 'Object' && !ASTAnalyzer.isPrimitiveOrWrapper(itemType)
+      ? { $ref: `#/components/schemas/${itemType}` }
+      : ASTAnalyzer.javaTypeToOpenAPI(itemType),
+  };
+
+  // Create pagination headers (pagination info is passed via headers)
+  const headers: Record<string, HeaderInfo> = {
+    'X-Total-Count': {
+      schema: { type: 'integer' },
+      description: 'Total number of items',
+    },
+    'X-Offset': {
+      schema: { type: 'integer' },
+      description: 'Current offset',
+    },
+    'X-Limit': {
+      schema: { type: 'integer' },
+      description: 'Current limit',
+    },
+  };
+
+  return {
+    statusCode: '200',
+    description: 'Successful response',
+    contentType: 'application/json',
+    schema: arraySchema,
+    headers,
+  };
+}
+
+/**
+ * Extract the main type from a generic type string
+ * e.g., "UserDTO" from "UserDTO" or "List<String>" -> "List"
+ */
+function extractMainType(genericType: string): string {
+  // Remove any nested generics to get the main type
+  const match = genericType.match(/^([^<]+)/);
+  if (match) {
+    return match[1].trim();
+  }
+  return genericType;
+}
+
+/**
+ * Extract nested generic type
+ * e.g., "List<String>" -> "String", "PaginatedList<UserDTO>" -> "UserDTO"
+ */
+function extractNestedGenericType(genericType: string): string | undefined {
+  const match = genericType.match(/<(.+)>$/);
+  if (match) {
+    return match[1].trim();
+  }
+  return undefined;
+}