API Documentation Editor

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

💡 핵심 철학

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

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

// 사용자 정보 관리  👈 이 주석만으로 자동 그룹핑!
'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. 설치

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

2. 초기 설정

npx api-doc-setup

자동으로 설정되는 것들:

• ✅ scripts/generate-docs.js 복사
• ✅ package.json에 npm 스크립트 추가
• ✅ VSCode Extension 자동 설치
• ✅ .vscode/extensions.json 생성

3. VSCode 재시작

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

4. 문서 생성

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. ✅ 주석으로 그룹 구분

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

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

2. ✅ RESTful 경로 사용

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

3. ✅ 일관된 핸들러명

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 작성

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: 문서 생성

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. 그룹 자동 분류

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

// 사용자 정보 관리
'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} 등을 자동으로 파라미터로 인식합니다.

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

자동 생성:

parameters:
  - name: id
    in: path
    required: true
    schema:
      type: string

3. Internal API 자동 표시

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

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

생성 결과: x-visibility: internal

4. Deprecated API 자동 표시

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

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

생성 결과: deprecated: true

🎨 주석 작성 Best Practices

✅ 좋은 예시:

// 사용자 정보 관리
'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,

❌ 피해야 할 예시:

// 주석 없음 - 그룹 분류 안 됨
'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 | 삭제 |

✨ 핸들러명 네이밍 규칙

// 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 작성

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)

npm run docs:generate

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 설치 확인:

code --list-extensions | grep api-doc-viewer

2. Extension이 없다면 재설치:

npx api-doc-setup

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

문서가 생성되지 않아요

확인 사항:

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

디버그:

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. 문서 생성 먼저 실행:

   npm run docs:generate

2. 프로젝트 파일 열기:

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

3. 수동 새로고침:

   • API Documentation 사이드바에서 새로고침 버튼 클릭

📌 자주 사용하는 명령어

# 문서 생성
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 - 설정 및 커스터마이징 가이드

또는 터미널에서:

# 설치 후 문서 보기
cat node_modules/@lgbusinesscloud/api-doc-editor/GETTING_STARTED.md
cat node_modules/@lgbusinesscloud/api-doc-editor/ROUTER_GUIDE.md

📄 License

MIT