REST API 정보 추출

REST API 정보 추출

이 Skill은 Spring Boot 백엔드 프로젝트에서 REST API 엔드포인트 정보를 자동으로 추출하여 프론트엔드 개발자에게 전달할 수 있는 형태로 정리합니다.

Instructions

다음 단계를 따라 API 정보를 추출하세요:

1. Controller 파일 찾기

• src/​main/​kotlin/​com/​sight/​controllers/​http/ 디렉토리에서 모든 *Controller.kt 파일을 찾습니다
• InternalApiController나 TestController 같은 내부용 API는 제외할 수 있습니다
• 찾은 컨트롤러 파일 중 주어진 프롬프트와 관련된 컨트롤러만 추출합니다

2. 각 Controller 분석

각 Controller 파일에서 다음 정보를 추출합니다:

• HTTP 메서드: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping
• 경로: 매핑 어노테이션의 값 (예: @GetMapping("/​users/​@me"))
• 권한: @Auth 어노테이션의 UserRole 배열
• 요청 DTO: @RequestBody, @ModelAttribute, @PathVariable, @RequestParam이 붙은 파라미터
• 응답 DTO: 메서드의 반환 타입
• 상태 코드: @ResponseStatus 어노테이션 또는 ResponseEntity 사용 여부

3. DTO 정보 수집

Request/​Response DTO가 있는 경우:

• src/​main/​kotlin/​com/​sight/​controllers/​http/​dto/ 디렉토리에서 해당 DTO 파일을 찾습니다
• DTO의 필드 이름과 타입을 추출합니다

4. 출력 형식

다음과 같은 형식으로 API 정보를 정리합니다:

# API 엔드포인트 목록

## [Controller 이름]

### [HTTP METHOD] [경로]
- **권한**: [필요한 권한 목록]
- **설명**: [엔드포인트 설명]
- **요청 파라미터**:
  - [파라미터명] ([타입]): [설명]
- **요청 본문** (있는 경우):
  ```typescript
  {
    필드명: 타입,
  }

• 응답:

  {
    필드명: 타입,
  }
  

• 상태 코드: [HTTP 상태 코드]
• 파일 참조: [파일경로]:[라인번호]

### 5. TypeScript 타입 변환
Kotlin 타입을 TypeScript 타입으로 변환:
- `String` → `string`
- `Int`, `Long` → `number`
- `Boolean` → `boolean`
- `LocalDateTime`, `Instant` → `string` (ISO 8601 형식)
- `List<T>` → `T[]`
- `Map<K, V>` → `Record<K, V>`
- nullable 타입 (`T?`) → `T | null`

## Examples

### 예시 1: 단순 GET 엔드포인트
```kotlin
@Auth([UserRole.USER, UserRole.MANAGER])
@GetMapping("/​users/​@me")
fun getCurrentUser(requester: Requester): GetCurrentUserResponse

출력:

### GET /​users/​@me
- **권한**: USER, MANAGER
- **설명**: 현재 로그인한 사용자 정보 조회
- **응답**:
  ```typescript
  {
    id: string,
    name: string,
    manager: boolean,
    status: string,
    studentStatus: string,
    createdAt: string,
    updatedAt: string
  }

• 파일 참조: src/​main/​kotlin/​com/​sight/​controllers/​http/​UserController.kt:28

### 예시 2: POST 엔드포인트 (Request Body 포함)
```kotlin
@Auth([UserRole.MANAGER])
@PostMapping("/​transactions")
@ResponseStatus(HttpStatus.CREATED)
fun createTransaction(
    @Valid @RequestBody request: CreateTransactionRequest,
    requester: Requester,
): CreateTransactionResponse

출력:

### POST /​transactions
- **권한**: MANAGER
- **설명**: 새 거래 내역 생성
- **요청 본문**:
  ```typescript
  {
    item: string,
    price: number,
    quantity: number,
    place: string | null,
    note: string | null,
    usedAt: string  // ISO 8601 datetime
  }

• 응답:

  {
    id: string,
    author: string,
    item: string,
    price: number,
    quantity: number,
    total: number,
    cumulative: number,
    place: string | null,
    note: string | null,
    usedAt: string,
    createdAt: string
  }
  

• 상태 코드: 201 Created
• 파일 참조: src/​main/​kotlin/​com/​sight/​controllers/​http/​TransactionController.kt:72

### 예시 3: Query Parameters 포함
```kotlin
@Auth([UserRole.USER, UserRole.MANAGER])
@GetMapping("/​transactions")
fun getTransactions(
    @RequestParam year: Int,
    @RequestParam(defaultValue = "0") @Min(0) offset: Int,
    @RequestParam(defaultValue = "20") @Min(1) @Max(50) limit: Int,
): ListTransactionsResponse

출력:

### GET /​transactions
- **권한**: USER, MANAGER
- **설명**: 거래 내역 목록 조회
- **요청 파라미터**:
  - year (number): 조회할 연도 (필수)
  - offset (number): 페이지 오프셋 (기본값: 0)
  - limit (number): 페이지 크기 (기본값: 20)
- **응답**:
  ```typescript
  {
    count: number,
    transactions: Array<{
      id: string,
      author: string,
      item: string,
      price: number,
      quantity: number,
      total: number,
      cumulative: number,
      place: string | null,
      note: string | null,
      usedAt: string,
      createdAt: string,
      updatedAt: string
    }>
  }

• 파일 참조: src/​main/​kotlin/​com/​sight/​controllers/​http/​TransactionController.kt:32

## Tips

1. **그룹화**: Controller별로 엔드포인트를 그룹화하여 가독성을 높입니다
2. **정렬**: 각 그룹 내에서 경로 알파벳 순으로 정렬합니다
3. **상세 수준**: 사용자가 "간단하게" 또는 "상세하게"를 요청하면 DTO 필드 포함 여부를 조정합니다
4. **필터링**: 특정 Controller나 경로 패턴만 추출하고 싶다면 사용자에게 확인합니다
5. **OpenAPI**: 가능하다면 OpenAPI/​Swagger 형식으로도 출력할 수 있습니다