npm package: @lgbusinesscloud/api-doc-editor
Description: Automatic API documentation generator and editor for lg businesscloud structure projects
Author: taegyun1.kim@lge.com
Latest version: 1.0.3

# API Documentation Editor

**router.js만 작성하면 완벽한 API 문서가 자동 생성됩니다!** 📝

---

## 💡 핵심 철학

**"router.js만 잘 작성하면 문서는 자동으로 만들어진다!"**

개발자는 router.js에 주석과 경로만 작성하면 됩니다. 나머지는 모두 자동입니다.

```javascript
// 사용자 정보 관리  👈 이 주석만으로 자동 그룹핑!
'GET /user/users': handler.getAllUsers,
'POST /user/users': handler.createUser,

// 사용자 인증
'POST /user/auth/login': handler.login,
```

↓ **자동 생성** ↓

✅ OpenAPI 3.0 문서 (YAML + JSON)
✅ REST Client 테스트 파일
✅ VSCode에서 바로 편집 가능

---

## 🚀 빠른 시작

### 1. 설치

```bash
npm install @lgbusinesscloud/api-doc-editor --save-dev
```

### 2. 초기 설정

```bash
npx api-doc-setup
```

자동으로 설정되는 것들:
- ✅ `scripts/generate-docs.js` 복사
- ✅ `package.json`에 npm 스크립트 추가
- ✅ VSCode Extension 자동 설치
- ✅ `.vscode/extensions.json` 생성

### 3. VSCode 재시작

Extension 활성화를 위해 VSCode를 완전히 재시작하세요.

### 4. 문서 생성

```bash
npm run docs:generate
```

**완료!** 🎉

---

## 🎯 주요 기능

### ✨ router.js 기반 자동 생성
- **주석 → 그룹**: `// 그룹명` 주석으로 자동 분류
- **경로 → API**: RESTful 경로에서 자동 추출
- **`{id}` → 파라미터**: Path parameters 자동 인식
- **`/internal/` → Internal API**: 자동 표시
- **`/v1/` → Deprecated**: 자동 표시

### 🎨 VSCode 통합 편집기
- **사이드바 트리 뷰**: 모든 API 엔드포인트를 계층 구조로 표시
- **폼 기반 편집**: YAML 문법 없이 간편하게 편집
- **자동 저장**: YAML/JSON 파일 동시 업데이트
- **빠른 접근**: router.js 우클릭 → "Open in API Documentation"

### 📝 다양한 출력 형식
- **OpenAPI 3.0 YAML/JSON**: 표준 API 문서
- **REST Client .http**: VSCode에서 바로 API 테스트

---

## 📝 router.js 작성 규칙 (3가지만!)

### 1. ✅ 주석으로 그룹 구분

```javascript
// 사용자 정보 관리  👈 이 주석 하나면 자동 그룹핑
'GET /user/users': handler.getAllUsers,
'POST /user/users': handler.createUser,

// 사용자 인증  👈 새로운 그룹 시작
'POST /user/auth/login': handler.login,
```

### 2. ✅ RESTful 경로 사용

```javascript
'GET /user/users'           // 목록 조회
'POST /user/users'          // 생성
'GET /user/users/{id}'      // 상세 조회
'PUT /user/users/{id}'      // 수정
'DELETE /user/users/{id}'   // 삭제
```

### 3. ✅ 일관된 핸들러명

```javascript
handler.getAllUsers      // get + All + Users
handler.getUserById      // get + User + ById
handler.createUser       // create + User
handler.updateUser       // update + User
handler.deleteUser       // delete + User
```

**이 3가지만 지키면 완벽한 API 문서가 자동으로 생성됩니다!**

---

## 💡 개발자 워크플로우

### Step 1: router.js 작성

```javascript
const UserHandler = require('./handler/user_handler');

const userRouter = async (event, context) => {
  const handler = new UserHandler(event, context);

  const routeKey = `${event.httpMethod} ${event.resource}`;
  const routeMap = {
    // 사용자 정보 관리
    'GET /user/users': handler.getAllUsers,
    'POST /user/users': handler.createUser,
    'GET /user/users/{id}': handler.getUserById,

    // 사용자 인증
    'POST /user/auth/login': handler.login,
    'POST /user/auth/logout': handler.logout,
  };

  if (routeMap[routeKey]) {
    return await routeMap[routeKey](event, context);
  }
  return { statusCode: 404, body: 'Not found' };
};

module.exports.router = userRouter;
```

### Step 2: 문서 생성

```bash
npm run docs:generate
```

자동으로 생성되는 것:
- ✅ `docs/user.openapi.yaml` - OpenAPI 3.0 문서
- ✅ `docs/user.openapi.json` - JSON 형식
- ✅ `docs/user.http` - REST Client 테스트 파일

### Step 3: (선택) VSCode에서 상세 정보 추가

1. 📖 **API Documentation** 사이드바 열기
2. **USER** → **사용자 정보 관리** → **GET /user/users** 클릭
3. 폼에서 추가 정보 입력 (Parameters, Responses 등)
4. 💾 **Save Changes** → YAML 자동 업데이트!

**끝! 이게 전부입니다.** 🎉

---

## 🎓 VSCode Extension 사용법

### 📖 사이드바에서 문서 보기

1. **API Documentation 사이드바 열기**
   - 왼쪽 Activity Bar에서 📖 (책 아이콘) 클릭

2. **엔드포인트 편집**
   - 모듈 → 그룹 → 엔드포인트 클릭
   - 폼에서 상세 정보 입력:
     - Summary (요약)
     - Parameters (파라미터 JSON)
     - Responses (응답 JSON)
   - **Save Changes** 클릭 → YAML/JSON 자동 업데이트

3. **빠른 접근**
   - `router.js` 파일에서 우클릭
   - "Open in API Documentation" 선택
   - → 해당 프로젝트의 API 문서만 표시됩니다!

## 📝 router.js 작성 상세 가이드

### 🎯 핵심 3가지 규칙

1. **✅ 주석으로 그룹핑** - `// 그룹명` 형식
2. **✅ RESTful 경로** - `GET /module/resource` 형식
3. **✅ 일관된 핸들러명** - `handler.동사명사` 형식

### 📋 자동 감지 기능

#### 1. 그룹 자동 분류
주석 바로 다음 줄부터 다음 주석 전까지를 하나의 그룹으로 자동 분류합니다.

```javascript
// 사용자 정보 관리
'GET /user/users': handler.getAllUsers,
'POST /user/users': handler.createUser,

// 사용자 인증
'POST /user/auth/login': handler.login,
'POST /user/auth/logout': handler.logout,
```

**생성 결과:**
- 그룹: "사용자 정보 관리" (2개 API)
- 그룹: "사용자 인증" (2개 API)

#### 2. Path Parameters 자동 추출
중괄호 `{id}`, `{userId}` 등을 자동으로 파라미터로 인식합니다.

```javascript
'GET /user/users/{id}': handler.getUserById,
'PUT /device/devices/{deviceId}/settings': handler.updateSettings,
```

**자동 생성:**
```yaml
parameters:
  - name: id
    in: path
    required: true
    schema:
      type: string
```

#### 3. Internal API 자동 표시
경로가 `/internal/`로 시작하면 자동으로 Internal API로 표시됩니다.

```javascript
// 내부 API
'GET /internal/user/audit': handler.getAuditLogs,
'POST /internal/user/sync': handler.syncUsers,
```

**생성 결과:** `x-visibility: internal`

#### 4. Deprecated API 자동 표시
경로가 `/v1/`, `/v2/` 등으로 시작하면 자동으로 Deprecated로 표시됩니다.

```javascript
// 레거시 API
'GET /v1/user/list': handler.getUserListV1,
```

**생성 결과:** `deprecated: true`

### 🎨 주석 작성 Best Practices

**✅ 좋은 예시:**
```javascript
// 사용자 정보 관리
'GET /user/users': handler.getAllUsers,
'POST /user/users': handler.createUser,
'GET /user/users/{id}': handler.getUserById,
'PUT /user/users/{id}': handler.updateUser,
'DELETE /user/users/{id}': handler.deleteUser,

// 사용자 프로필
'GET /user/profile': handler.getMyProfile,
'PUT /user/profile': handler.updateProfile,
```

**❌ 피해야 할 예시:**
```javascript
// 주석 없음 - 그룹 분류 안 됨
'GET /user/users': handler.getAllUsers,
'POST /user/users': handler.createUser,

// 너무 세분화된 주석
// 모든 사용자 조회
'GET /user/users': handler.getAllUsers,
// 사용자 생성
'POST /user/users': handler.createUser,
```

### 📌 RESTful 경로 규칙

| HTTP Method | 경로 패턴 | 핸들러명 예시 | 설명 |
|------------|----------|--------------|------|
| **GET** | `/resource` | `getAllResources` | 목록 조회 |
| **GET** | `/resource/{id}` | `getResourceById` | 상세 조회 |
| **POST** | `/resource` | `createResource` | 생성 |
| **PUT** | `/resource/{id}` | `updateResource` | 전체 수정 |
| **PATCH** | `/resource/{id}` | `patchResource` | 부분 수정 |
| **DELETE** | `/resource/{id}` | `deleteResource` | 삭제 |

### ✨ 핸들러명 네이밍 규칙

```javascript
// CRUD 기본 패턴
handler.getAllUsers       // get + All + Users
handler.getUserById       // get + User + ById
handler.createUser        // create + User
handler.updateUser        // update + User
handler.deleteUser        // delete + User

// 비즈니스 로직 패턴
handler.login             // 동사
handler.logout            // 동사
handler.verifyToken       // 동사 + 명사
handler.refreshToken      // 동사 + 명사
handler.assignRole        // 동사 + 명사
handler.changePassword    // 동사 + 명사
```

### 🔧 실전 예시

#### Before: router.js 작성
```javascript
const OrderHandler = require('./handler/order_handler');

const orderRouter = async (event, context) => {
  const handler = new OrderHandler(event, context);
  const routeKey = `${event.httpMethod} ${event.resource}`;

  const routeMap = {
    // 주문 정보 관리
    'GET /order/orders': handler.getAllOrders,
    'POST /order/orders': handler.createOrder,
    'GET /order/orders/{id}': handler.getOrderById,
    'PUT /order/orders/{id}': handler.updateOrder,
    'DELETE /order/orders/{id}': handler.deleteOrder,

    // 주문 상태 관리
    'PATCH /order/orders/{id}/status': handler.updateOrderStatus,
    'GET /order/orders/{id}/history': handler.getOrderHistory,

    // 주문 결제
    'POST /order/orders/{id}/payment': handler.processPayment,
    'GET /order/orders/{id}/payment': handler.getPaymentInfo,
  };

  if (routeMap[routeKey]) {
    return await routeMap[routeKey](event, context);
  }
  return { statusCode: 404, body: 'Not found' };
};

module.exports.router = orderRouter;
```

#### After: 자동 생성된 문서 (docs/order.openapi.yaml)
```bash
npm run docs:generate
```

```yaml
openapi: 3.0.3
info:
  title: ORDER API
  version: 1.0.0
tags:
  - name: 주문 정보 관리
    description: 주문 정보 관리 operations
  - name: 주문 상태 관리
    description: 주문 상태 관리 operations
  - name: 주문 결제
    description: 주문 결제 operations
paths:
  /order/orders:
    get:
      summary: GET /order/orders
      tags: [주문 정보 관리]
      responses:
        '200': { description: Success }
        '400': { description: Bad Request }
        '500': { description: Internal Server Error }
      x-handler: handler.getAllOrders
    post:
      summary: POST /order/orders
      tags: [주문 정보 관리]
      # ...
  /order/orders/{id}:
    get:
      summary: GET /order/orders/{id}
      tags: [주문 정보 관리]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      # ...
```

---

## ❓ 문제 해결 (Troubleshooting)

### VSCode Extension이 안 보여요

**해결 방법:**

1. Extension 설치 확인:
```bash
code --list-extensions | grep api-doc-viewer
```

2. Extension이 없다면 재설치:
```bash
npx api-doc-setup
```

3. **VSCode 완전 재시작** (중요!)
   - 모든 VSCode 창을 닫고 다시 열기
   - 단순 "Reload Window"가 아닌 완전 재시작

### 문서가 생성되지 않아요

**확인 사항:**

1. **router.js 파일 위치**: `src/*/router.js` 패턴에 맞는지 확인
2. **주석 확인**: `// 그룹명` 형식의 주석이 있는지 확인
3. **routeMap 확인**: `const routeMap = { ... }` 또는 `const map = { ... }` 형태인지 확인

**디버그:**
```bash
node scripts/generate-docs.js
```

### 특정 모듈만 Endpoints: 0으로 나와요

**원인:** router.js가 다른 패턴을 사용 중일 수 있습니다.

**지원하는 패턴:**
1. `const routeMap = { 'GET /path': handler.method }`
2. `const map = { 'GET /path': handler.method }`
3. `'GET /path': { handler: handler.method, license: 'xxx' }`
4. `switch-case` 문: `case 'GET /path':`

**해결:**
위 패턴 중 하나로 router.js를 작성하거나, 이슈를 제기해주세요.

### API Documentation 사이드바가 비어있어요

**원인:** 현재 열린 파일의 프로젝트에 docs 폴더가 없을 수 있습니다.

**해결:**
1. **문서 생성 먼저 실행**:
   ```bash
   npm run docs:generate
   ```

2. **프로젝트 파일 열기**:
   - `src/*/router.js` 파일을 VSCode에서 열기
   - Extension이 자동으로 해당 프로젝트의 docs를 감지합니다

3. **수동 새로고침**:
   - API Documentation 사이드바에서 새로고침 버튼 클릭

---

## 📌 자주 사용하는 명령어

```bash
# 문서 생성
npm run docs:generate

# 초기 설정 (VSCode Extension 설치)
npx api-doc-setup

# VSCode Extension 재설치 (문제 발생 시)
npx api-doc-setup
```

---
## 📚 추가 문서

패키지 설치 후 `node_modules/@lgbusinesscloud/api-doc-editor/` 폴더에서 다음 문서를 확인하세요:

- **GETTING_STARTED.md** - 5분 안에 시작하기 (설치부터 첫 문서 생성까지)
- **ROUTER_GUIDE.md** - router.js 작성 상세 가이드 (주석, 패턴, 베스트 프랙티스)
- **SETUP_GUIDE.md** - 설정 및 커스터마이징 가이드

또는 터미널에서:
```bash
# 설치 후 문서 보기
cat node_modules/@lgbusinesscloud/api-doc-editor/GETTING_STARTED.md
cat node_modules/@lgbusinesscloud/api-doc-editor/ROUTER_GUIDE.md
```

---

## 📄 License

MIT