@g1cloud/api-gen 1.0.0

package/prompt/01_Initial.md

@@ -0,0 +1,358 @@
+# Spring Boot → OpenAPI v3 YAML 생성기 개발
+
+TypeScript로 Spring Boot 애플리케이션의 Java 소스코드를 분석하여 OpenAPI Specification v3 기반의 YAML 파일을 자동 생성하는 CLI 도구를 만들어주세요. 도구 이름은 `@g1cloud/api-gen` 으로 해주고, 현재 디렉토리 아래에 `api-gen` 디렉토리를 만들어 프로젝트 루트 디렉토리로 사용하세요.
+
+## 주요 기능 요구사항
+
+### 1. Java 소스코드 파싱
+- `java-parser` 또는 `tree-sitter-java` NPM 패키지를 사용하여 Java 파일 파싱
+- AST(Abstract Syntax Tree)를 분석하여 어노테이션 및 메서드 시그니처 추출
+
+### 2. RestController 분석
+다음 어노테이션들을 분석:
+- `@RestController` / `@Controller` + `@ResponseBody`
+- `@RequestMapping` (클래스/메서드 레벨)
+- `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`
+
+### 3. 입력 파라미터 분석
+각 엔드포인트의 파라미터를 분석하여 OpenAPI 스키마 생성:
+- `@RequestParam` → query parameters
+- `@PathVariable` → path parameters
+- `@RequestBody` → request body schema
+- `@RequestHeader` → header parameters
+- 파라미터의 타입, 필수 여부(`required`), 기본값(`defaultValue`) 추출
+
+#### 특수 타입 처리: SearchParam
+파라미터에 `SearchParam` 타입의 객체가 있는 경우, 다음 query parameters를 자동으로 추가:
+- `offset` (integer) - 페이지네이션 오프셋
+- `limit` (integer) - 페이지네이션 제한
+- `filter` (Filter 타입) - 필터 조건 (객체 스키마로 확장)
+- `sort` (Sort 타입) - 정렬 조건 (객체 스키마로 확장)
+```yaml
+# SearchParam 예시
+parameters:
+  - name: offset
+    in: query
+    schema:
+      type: integer
+    description: Pagination offset
+  - name: limit
+    in: query
+    schema:
+      type: integer
+    description: Pagination limit
+  - name: filter
+    in: query
+    schema:
+      $ref: '#/components/schemas/Filter'
+  - name: sort
+    in: query
+    schema:
+      $ref: '#/components/schemas/Sort'
+```
+
+### 4. 출력 데이터 형식 분석
+- 메서드 리턴 타입 분석 (`ResponseEntity<T>`, DTO 클래스 등)
+- 리턴 타입의 클래스 구조를 분석하여 response schema 생성
+- 중첩 객체(nested objects), 제네릭 타입 지원
+- HTTP 상태 코드 추출
+
+#### 특수 타입 처리: PaginatedList
+리턴 타입이 `PaginatedList` 또는 `PaginatedList<T>` 인 경우, response headers에 다음을 추가:
+- `X-Total-Count` (integer) - 전체 아이템 개수
+- `X-Offset` (integer) - 현재 오프셋
+- `X-Limit` (integer) - 현재 제한 값
+```yaml
+# PaginatedList 예시
+responses:
+  '200':
+    description: Successful response
+    headers:
+      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
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/PaginatedListUserDTO'
+```
+
+### 5. 보안/권한 분석
+- `@PreAuthorize` / `@PostAuthorize` 어노테이션 분석
+- `@Secured` 어노테이션 분석
+- SpEL 표현식에서 역할(role) 및 권한(authority) 추출
+  - `hasRole('ADMIN')` → ROLE_ADMIN
+  - `hasAnyRole('USER', 'ADMIN')` → [ROLE_USER, ROLE_ADMIN]
+  - `hasAuthority('READ_PRIVILEGE')` → READ_PRIVILEGE
+- **복잡한 SpEL 표현식 처리**: `hasRole`, `hasAnyRole`, `hasAuthority` 이외의 구문이 포함된 경우, 전체 SpEL 표현식을 `x-security-expression` 확장 필드에 그대로 기록
+```yaml
+# 복잡한 SpEL 표현식 예시
+paths:
+  /api/users/{id}:
+    put:
+      security:
+        - bearerAuth: []
+      x-required-roles:
+        - ROLE_USER
+      x-security-expression: "hasRole('ADMIN') or (#user.id == #id and hasRole('USER'))"
+```
+
+- OpenAPI의 `security` 필드 또는 `x-required-roles` 확장 필드에 문서화
+
+### 6. DTO 스키마 생성
+- `@RequestBody`와 리턴 타입에 사용된 DTO 클래스 재귀적 분석
+- 필드 타입, 어노테이션(`@NotNull`, `@Size` 등) 분석
+- OpenAPI components/schemas에 스키마 정의 생성
+- `SearchParam`, `Filter`, `Sort`, `PaginatedList` 타입도 스키마로 정의
+
+## 기술 스택
+- **언어**: TypeScript
+- **Java 파서**: `java-parser` 또는 `tree-sitter-java`
+- **YAML 생성**: `js-yaml`
+- **CLI**: `commander` 또는 `yargs`
+
+## CLI 인터페이스
+```bash
+# 사용 예시
+npx spring-to-openapi \
+  --source ./src/main/java \
+  --output ./openapi.yaml \
+  --title "My API" \
+  --version "1.0.0" \
+  --base-path "/api"
+```
+
+### CLI 옵션
+- `--source, -s`: Java 소스코드 디렉토리 경로 (필수)
+- `--output, -o`: 출력 YAML 파일 경로 (기본값: `openapi.yaml`)
+- `--title, -t`: API 제목 (기본값: `API Documentation`)
+- `--version, -v`: API 버전 (기본값: `1.0.0`)
+- `--base-path, -b`: API 베이스 경로 (선택)
+
+## 출력 형식 예시
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+servers:
+  - url: http://localhost:8080/api
+paths:
+  /users:
+    get:
+      summary: Search users with pagination
+      parameters:
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          description: Pagination offset
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Pagination limit
+        - name: filter
+          in: query
+          schema:
+            $ref: '#/components/schemas/Filter'
+        - name: sort
+          in: query
+          schema:
+            $ref: '#/components/schemas/Sort'
+      responses:
+        '200':
+          description: Successful response
+          headers:
+            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
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedListUserDTO'
+      security:
+        - bearerAuth: []
+      x-required-roles:
+        - ROLE_USER
+  
+  /users/{id}:
+    get:
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserDTO'
+      security:
+        - bearerAuth: []
+      x-required-roles:
+        - ROLE_USER
+        - ROLE_ADMIN
+    
+    put:
+      summary: Update user
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserDTO'
+      responses:
+        '200':
+          description: Successful response
+      security:
+        - bearerAuth: []
+      x-security-expression: "hasRole('ADMIN') or (#user.id == #id and hasRole('USER'))"
+
+components:
+  schemas:
+    UserDTO:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        email:
+          type: string
+    
+    PaginatedListUserDTO:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/UserDTO'
+        total:
+          type: integer
+        offset:
+          type: integer
+        limit:
+          type: integer
+    
+    Filter:
+      type: object
+      description: Filter conditions
+      additionalProperties: true
+    
+    Sort:
+      type: object
+      description: Sort conditions
+      properties:
+        field:
+          type: string
+        direction:
+          type: string
+          enum: [ASC, DESC]
+  
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+## 추가 요구사항
+- 에러 핸들링: 파싱 실패 시 명확한 에러 메시지 출력
+- 로깅: 처리 진행 상황 표시 (발견된 컨트롤러 수, 엔드포인트 수 등)
+- 테스트: 샘플 Java 파일로 테스트 가능하도록 예제 포함
+  - SearchParam을 사용하는 예제
+  - PaginatedList를 반환하는 예제
+  - 복잡한 SpEL 표현식을 사용하는 예제
+- README.md: 설치 및 사용법 문서 작성
+
+## 프로젝트 구조
+```
+spring-to-openapi/
+├── src/
+│   ├── index.ts           # CLI 진입점
+│   ├── parser/
+│   │   ├── javaParser.ts  # Java 파싱 로직
+│   │   └── astAnalyzer.ts # AST 분석
+│   ├── analyzer/
+│   │   ├── controllerAnalyzer.ts   # RestController 분석
+│   │   ├── parameterAnalyzer.ts    # 파라미터 분석 (SearchParam 특수 처리)
+│   │   ├── responseAnalyzer.ts     # 응답 분석 (PaginatedList 특수 처리)
+│   │   ├── securityAnalyzer.ts     # 보안 어노테이션 분석 (SpEL 파싱)
+│   │   └── schemaGenerator.ts      # DTO 스키마 생성
+│   ├── generator/
+│   │   └── openapiGenerator.ts     # OpenAPI YAML 생성
+│   └── types/
+│       └── index.ts        # TypeScript 타입 정의
+├── examples/              # 테스트용 샘플 Java 파일
+│   ├── UserController.java
+│   ├── SearchParam.java
+│   └── PaginatedList.java
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 특수 타입 처리 상세
+
+### SearchParam 감지 및 처리
+1. 메서드 파라미터 타입이 `SearchParam` 또는 이를 상속/구현하는 타입인지 확인
+2. 해당 파라미터가 발견되면 자동으로 `offset`, `limit`, `filter`, `sort` query parameters 추가
+3. `Filter`와 `Sort` 타입이 정의되어 있다면 해당 스키마를 components/schemas에 추가
+
+### PaginatedList 감지 및 처리
+1. 메서드 리턴 타입이 `PaginatedList` 또는 `PaginatedList<T>`인지 확인
+2. 제네릭 타입 `T`를 추출하여 실제 아이템 타입 파악
+3. Response에 `X-Total-Count`, `X-Offset`, `X-Limit` 헤더 자동 추가
+4. Response body 스키마는 PaginatedList 구조로 생성
+
+### SpEL 표현식 처리
+1. `@PreAuthorize`, `@PostAuthorize` 어노테이션의 값 추출
+2. 정규식으로 `hasRole()`, `hasAnyRole()`, `hasAuthority()` 패턴 매칭
+3. 단순 패턴에 매칭되면 역할/권한 추출하여 `x-required-roles`에 추가
+4. 복잡한 표현식(논리 연산자, 비교 연산자, 변수 참조 등 포함)이면 전체 표현식을 `x-security-expression`에 기록
+5. 두 필드 모두 존재할 수 있음 (간단한 역할 + 복잡한 전체 표현식)
+
+### MultiLangString 처리
+1. `MultiLangString` 은 `Map<String, String>` 형태로 처리
+2. OpenAPI 스키마에서 `type: object`로 정의하고, `additionalProperties: { type: string }` 사용
+
+### MultiLangStoredFile 처리
+1. `MultiLangStoredFile` 은 `Map<String, StoredFile>` 형태로 처리
+2. OpenAPI 스키마에서 `type: object`로 정의하고, `additionalProperties`에 `StoredFile` 스키마 참조 사용
+3. StoredFile 은 `net.g1project.bluecomm.model.StoredFile` 클래스 참고해서 처리
+
+### 그 외 Dto 분석 시 주의할 점
+- static field 는 제외
+- java.lang.Object 의 field 는 제외
+
+
+위 요구사항에 따라 완전히 동작하는 프로젝트를 생성해주세요.

package/prompt/02_/354/266/224/352/260/200.md

@@ -0,0 +1,31 @@
+# RestController 파일 별로 문서 생성
+
+디렉토리 하위의 @RestController annotation 이 추가된 파일을 검색해
+각각의 java 파일별로 별도의 yaml 파일을 생성하도록 할 것.
+yaml 파일 명은 java 파일명과 동일하게 할 것.
+
+이렇게 하려면 output 을 파일로 받지 않고 디렉토리로 받아야 함. (--out-dir 처럼)
+
+# javadoc 내용을 설명으로
+
+Java 소스코드에 작성된 javadoc 내용을 OpenAPI 문서의 설명(description) 필드로 포함시켜줘.
+
+
+# redoc 적용 스크립트
+
+각 yaml 파일 별로 @redocly/cli 를 실행하는 셸 스크립트 작성해줘.
+
+주어진 디렉토리 아래의 모든 yaml 파일에 대해서 아래처럼 실행
+
+npx @redocly/cli build-docs (yaml 파일) -o (타겟 디렉토리)
+
+# PaginatedList 스키마 정의
+
+PaginatedList 가 response 로 리턴될 때는 items 만 의미가 있고, totalCount, offset, limit 등은 response header 로 전달되기 때문에 표시하지 않도록 해줘.
+items 도 items property 는 명시하지 않고, 바로 배열 타입으로 정의되도록 해줘.
+
+예를 들어, PaginatedList<UserDto> 라면 마치 List<UserDto> 인 것처럼 response schema 가 생성되도록 해줘.
+
+# SearchParam
+
+SearchParam 의 Filter 와 Sort 는 그냥 object 타입으로 정의해줘.

package/src/analyzer/controllerAnalyzer.ts

@@ -0,0 +1,125 @@
+import {
+  JavaClass,
+  JavaMethod,
+  ControllerInfo,
+  EndpointInfo,
+  HttpMethod,
+  ProcessingContext,
+} from '../types';
+import { ASTAnalyzer } from '../parser/astAnalyzer';
+import { analyzeParameters } from './parameterAnalyzer';
+import { analyzeResponse } from './responseAnalyzer';
+import { analyzeMethodSecurity } from './securityAnalyzer';
+
+export class ControllerAnalyzer {
+  private context: ProcessingContext;
+
+  constructor(context: ProcessingContext) {
+    this.context = context;
+  }
+
+  /**
+   * Analyze all Java classes and extract controller information
+   * If apiSourcePath is specified, only analyze controllers within that directory
+   */
+  analyzeControllers(): ControllerInfo[] {
+    const controllers: ControllerInfo[] = [];
+    const { apiSourcePath } = this.context;
+
+    for (const [, javaClass] of this.context.javaClasses) {
+      // If apiSourcePath is specified, only include controllers from that directory
+      if (apiSourcePath && !javaClass.filePath.startsWith(apiSourcePath)) {
+        continue;
+      }
+
+      if (ASTAnalyzer.isRestController(javaClass)) {
+        const controllerInfo = this.analyzeController(javaClass);
+        if (controllerInfo) {
+          controllers.push(controllerInfo);
+        }
+      }
+    }
+
+    return controllers;
+  }
+
+  /**
+   * Analyze a single controller class
+   */
+  private analyzeController(javaClass: JavaClass): ControllerInfo | null {
+    const basePath = ASTAnalyzer.getClassBasePath(javaClass);
+    const endpoints: EndpointInfo[] = [];
+
+    console.log(`  Found controller: ${javaClass.name} (base path: ${basePath || '/'})`);
+
+    for (const method of javaClass.methods) {
+      if (ASTAnalyzer.isEndpointMethod(method)) {
+        const endpoint = this.analyzeEndpoint(javaClass, method, basePath);
+        if (endpoint) {
+          endpoints.push(endpoint);
+          console.log(`    - ${endpoint.method.toUpperCase()} ${endpoint.path}`);
+        }
+      }
+    }
+
+    if (endpoints.length === 0) {
+      return null;
+    }
+
+    return {
+      className: javaClass.name,
+      basePath,
+      endpoints,
+      javaClass,
+    };
+  }
+
+  /**
+   * Analyze a single endpoint method
+   */
+  private analyzeEndpoint(javaClass: JavaClass, method: JavaMethod, basePath: string): EndpointInfo | null {
+    const httpMethod = ASTAnalyzer.getHttpMethod(method);
+    if (!httpMethod) {
+      return null;
+    }
+
+    const methodPath = ASTAnalyzer.getMethodPath(method);
+    const fullPath = ASTAnalyzer.combinePaths(basePath, methodPath);
+
+    // Get @param descriptions from javadoc
+    const paramDescriptions = method.javadocInfo?.params || {};
+
+    // Analyze parameters (pass javadoc @param descriptions)
+    const { parameters, requestBody, hasSearchParam } = analyzeParameters(method, this.context, paramDescriptions);
+
+    // Analyze response
+    const { responses, hasPaginatedList, paginatedListItemType } = analyzeResponse(
+      method,
+      this.context
+    );
+
+    // Analyze security
+    const security = analyzeMethodSecurity(method);
+
+    return {
+      path: fullPath,
+      method: httpMethod as HttpMethod,
+      operationId: ASTAnalyzer.generateOperationId(javaClass.name, method.name),
+      summary: ASTAnalyzer.generateSummary(method.name),
+      description: method.javadoc,
+      returnDescription: method.javadocInfo?.returns,
+      parameters,
+      requestBody,
+      responses,
+      security,
+      hasSearchParam,
+      hasPaginatedList,
+      paginatedListItemType,
+    };
+  }
+}
+
+export function analyzeControllers(context: ProcessingContext): ControllerInfo[] {
+  const analyzer = new ControllerAnalyzer(context);
+  return analyzer.analyzeControllers();
+}