npm package: @lgbusinesscloud/api-spec-editor
Description: Simple text format to OpenAPI documentation generator with VS Code extension
Author: taegyun
Latest version: 0.0.5

# api-spec-editor

간단한 텍스트 포맷으로 API를 설계하고 OpenAPI 문서를 자동 생성하는 CLI 도구입니다.

[![npm version](https://badge.fury.io/js/api-spec-editor.svg)](https://www.npmjs.com/package/api-spec-editor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 왜 api-spec-editor인가?

- **JSON/YAML 없이** 직관적인 텍스트 포맷으로 API 정의
- **OpenAPI 3.0** 표준 문서 자동 생성 (YAML, JSON, Markdown)
- **VS Code Extension** 제공 - 트리뷰, 미리보기, 실시간 새로고침
- **API-First 개발** - 코드 작성 전 API 설계 및 검토

## 설치

```bash
npm i @lgbusinesscloud/api-spec-editor --save-dev
```

> VS Code 사용자는 **API Spec Viewer** 확장이 자동으로 설치됩니다.

## 빠른 시작

```bash
# 1. 새 API 스펙 생성
npx api-spec init user

# 2. 스펙 파일 편집 (api-specs/user.api.txt)

# 3. 문서 생성
npx api-spec generate

# 4. 결과 확인 (api-docs/ 폴더)
```

## 프로젝트 구조

```
your-project/
├── api-specs/              # API 스펙 파일 (입력)
│   ├── user.api.txt
│   ├── product.api.txt
│   └── order.api.txt
├── api-docs/               # 생성된 문서 (출력)
│   ├── user.openapi.yaml
│   ├── user.openapi.json
│   └── user.api-spec.md
└── package.json
```

---

## 스펙 파일 작성법

### 기본 구조

```
[모듈명]
title: API 제목
base: /기본경로

---

name: 엔드포인트 이름
path: METHOD /경로
group: 그룹명
desc: 설명

---

name: 다음 엔드포인트
...
```

### 문법 요약

| 문법 | 설명 | 예시 |
|------|------|------|
| `[모듈명]` | 모듈 헤더 | `[user]` |
| `schema Name:` | 스키마 정의 | `schema User: 사용자 정보` |
| `---` | 엔드포인트 구분자 | |
| `name:` | 엔드포인트 이름 | `name: Get User` |
| `path:` | HTTP 메서드 + 경로 | `path: GET /users/{id}` |
| `group:` | 그룹/태그 | `group: User Management` |
| `desc:` | 설명 | `desc: Get user by ID` |
| `param:` | Path 파라미터 | 아래 예시 참조 |
| `query:` | Query 파라미터 | 아래 예시 참조 |
| `header:` | Header | 아래 예시 참조 |
| `body:` | Request Body | 아래 예시 참조 |
| `response CODE:` | 응답 정의 | `response 200:` |
| `- field: type` | 필드 정의 | `- id: string` |
| `- required` | 필수 표시 (하위) | 아래 예시 참조 |
| `- desc:` | 필드 설명 (하위) | `- desc: 사용자 ID` |
| `- items[]: Type` | 배열 필드 | `- users[]: User` |

### 파라미터 정의 방식

#### 인라인 방식 (한 줄)

```
param: id (string, required) - User ID
query: page (number) - Page number
header: Authorization (string, required) - Bearer token
```

#### 하위 depth 방식 (여러 줄)

```
param: id
  - type: string
  - required
  - desc: User ID

query: page
  - type: number
  - desc: Page number (default: 1)

header: Authorization
  - type: string
  - required
  - desc: Bearer token
```

### 필드 정의 방식

#### 인라인 방식

```
body:
  - email: string (required)
  - name: string (required)
```

#### 하위 depth 방식

```
body:
  - email: string
    - required
    - desc: 사용자 이메일
  - name: string
    - required
    - desc: 사용자 이름
```

### 스키마 정의

재사용 가능한 데이터 타입을 정의합니다.

```
schema User: 사용자 정보
  - id: string
    - desc: 사용자 고유 ID
  - email: string
    - required
    - desc: 이메일 주소
  - name: string
    - desc: 사용자 이름
  - createdAt: string
    - desc: 생성일시
```

정의된 스키마는 body나 response에서 참조할 수 있습니다.

```
response 200:
  - users[]: User
  - total: number
```

---

## 예시

### 1. 사용자 관리 API

```
[user]
title: User API
base: /api/v1

schema User: 사용자 정보
  - id: string
    - desc: 사용자 고유 ID
  - email: string
    - required
    - desc: 이메일 주소
  - name: string
    - desc: 사용자 이름
  - role: string
    - desc: 사용자 역할
  - createdAt: string
    - desc: 생성일시
  - updatedAt: string
    - desc: 수정일시

---

name: Get Users
path: GET /users
group: User Management
desc: Get all users with pagination
query: page (number) - Page number (default: 1)
query: limit (number) - Items per page (default: 20)
query: search (string) - Search by name or email

response 200:
  - users[]: User
  - total: number
  - page: number
  - totalPages: number

---

name: Get User
path: GET /users/{id}
group: User Management
desc: Get user by ID
param: id (string) - User ID

response 200:
  - data: User
response 404: User not found

---

name: Create User
path: POST /users
group: User Management
desc: Create a new user

body:
  - email: string (required)
  - password: string (required)
  - name: string (required)
  - role: string

response 201:
  - data: User
response 400: Invalid input
response 409: Email already exists

---

name: Update User
path: PUT /users/{id}
group: User Management
desc: Update user information
param: id (string) - User ID

body:
  - email: string
  - name: string
  - role: string

response 200:
  - data: User
response 404: User not found

---

name: Delete User
path: DELETE /users/{id}
group: User Management
desc: Delete user by ID
param: id (string) - User ID

response 204:
response 404: User not found
```

### 2. 인증 API (하위 depth 방식)

```
[auth]
title: Authentication API
base: /api/v1/auth

---

name: Login
path: POST /login
group: Authentication
desc: User login with email and password

body:
  - email: string
    - required
  - password: string
    - required
  - rememberMe: boolean

response 200:
  - accessToken: string
  - refreshToken: string
  - expiresIn: number
  - user: object
response 401: Invalid credentials
response 429: Too many attempts

---

name: Refresh Token
path: POST /refresh
group: Authentication
desc: Refresh access token

body:
  - refreshToken: string
    - required

response 200:
  - accessToken: string
  - expiresIn: number
response 401: Invalid refresh token

---

name: Logout
path: POST /logout
group: Authentication
desc: Invalidate current session

header: Authorization
  - type: string
  - required
  - desc: Bearer token

response 204:
response 401: Unauthorized

---

name: Get Current User
path: GET /me
group: Authentication
desc: Get current authenticated user

header: Authorization
  - type: string
  - required
  - desc: Bearer token

response 200:
  - id: string
  - email: string
  - name: string
  - role: string
  - permissions[]: string
response 401: Unauthorized

---

name: Change Password
path: POST /change-password
group: Authentication
desc: Change current user password

header: Authorization
  - type: string
  - required
  - desc: Bearer token

body:
  - currentPassword: string
    - required
  - newPassword: string
    - required
  - confirmPassword: string
    - required

response 200:
  - message: string
response 400: Password mismatch
response 401: Invalid current password
```

### 3. 상품 및 주문 API

```
[product]
title: Product API
base: /api/v1

---

name: Get Products
path: GET /products
group: Product
desc: Get product list with filters
query: category (string) - Filter by category
query: minPrice (number) - Minimum price
query: maxPrice (number) - Maximum price
query: sort (string) - Sort by (price, name, createdAt)
query: order (string) - Sort order (asc, desc)
query: page (number) - Page number
query: limit (number) - Items per page

response 200:
  - products[]: Product
  - total: number
  - page: number
  - totalPages: number

---

name: Get Product
path: GET /products/{id}
group: Product
desc: Get product detail
param: id (string) - Product ID

response 200:
  - id: string
  - name: string
  - description: string
  - price: number
  - stock: number
  - category: string
  - images[]: string
  - createdAt: string
response 404: Product not found

---

name: Create Product
path: POST /products
group: Product
desc: Create a new product
header: Authorization (string, required) - Admin token

body:
  - name: string (required)
  - description: string
  - price: number (required)
  - stock: number (required)
  - category: string (required)
  - images[]: string

response 201:
  - id: string
  - name: string
  - price: number
response 400: Invalid input
response 401: Unauthorized
response 403: Forbidden

---

name: Create Order
path: POST /orders
group: Order
desc: Create a new order
header: Authorization (string, required) - Bearer token

body:
  - items[]: OrderItem (required)
  - shippingAddress: object (required)
  - paymentMethod: string (required)

response 201:
  - orderId: string
  - status: string
  - total: number
  - createdAt: string
response 400: Invalid input
response 401: Unauthorized

---

name: Get Order
path: GET /orders/{id}
group: Order
desc: Get order detail
header: Authorization (string, required) - Bearer token
param: id (string) - Order ID

response 200:
  - id: string
  - status: string
  - items[]: OrderItem
  - total: number
  - shippingAddress: object
  - createdAt: string
response 404: Order not found

---

name: Get My Orders
path: GET /orders
group: Order
desc: Get current user orders
header: Authorization (string, required) - Bearer token
query: status (string) - Filter by status
query: page (number) - Page number

response 200:
  - orders[]: Order
  - total: number
  - page: number
```

### 4. 파일 업로드 API

```
[file]
title: File Upload API
base: /api/v1/files

---

name: Upload File
path: POST /upload
group: File Management
desc: Upload a single file
header: Authorization (string, required) - Bearer token
header: Content-Type (string, required) - multipart/form-data

body:
  - file: file (required)
  - folder: string

response 201:
  - id: string
  - filename: string
  - originalName: string
  - mimeType: string
  - size: number
  - url: string
response 400: Invalid file type
response 413: File too large

---

name: Upload Multiple Files
path: POST /upload/multiple
group: File Management
desc: Upload multiple files (max 10)
header: Authorization (string, required) - Bearer token

body:
  - files[]: file (required)
  - folder: string

response 201:
  - files[]: FileInfo
  - count: number
response 400: Too many files

---

name: Get File
path: GET /{id}
group: File Management
desc: Get file info
param: id (string) - File ID

response 200:
  - id: string
  - filename: string
  - mimeType: string
  - size: number
  - url: string
  - createdAt: string
response 404: File not found

---

name: Delete File
path: DELETE /{id}
group: File Management
desc: Delete file
header: Authorization (string, required) - Bearer token
param: id (string) - File ID

response 204:
response 404: File not found
response 403: Forbidden
```

---

## CLI 명령어

### `api-spec init [module]`

새 API 스펙 파일 생성

```bash
npx api-spec init user          # api-specs/user.api.txt 생성
npx api-spec init product       # api-specs/product.api.txt 생성
npx api-spec init auth          # api-specs/auth.api.txt 생성
```

### `api-spec generate [module]`

문서 생성

```bash
npx api-spec generate           # 전체 모듈 생성
npx api-spec generate user      # user 모듈만 생성
npx api-spec generate --yaml    # YAML만 생성
npx api-spec generate --json    # JSON만 생성
npx api-spec generate --md      # Markdown만 생성
```

### `api-spec validate [module]`

스펙 검증

```bash
npx api-spec validate           # 전체 검증
npx api-spec validate user      # user 모듈 검증
```

### `api-spec list [module]`

엔드포인트 목록

```bash
npx api-spec list               # 전체 목록
npx api-spec list user          # user 모듈 목록
npx api-spec list --group       # 그룹별 출력
```

## 옵션

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `-d, --dir` | 스펙 파일 디렉토리 | `api-specs` |
| `-o, --output` | 출력 디렉토리 | `api-docs` |

```bash
npx api-spec init user -d specs
npx api-spec generate -d specs -o docs
```

---

## package.json 스크립트

```json
{
  "scripts": {
    "api:init": "api-spec init",
    "api:generate": "api-spec generate",
    "api:validate": "api-spec validate",
    "api:list": "api-spec list --group"
  }
}
```

```bash
npm run api:generate
```


npm 설치 시 **API Spec Viewer** 확장이 자동으로 설치됩니다.

### 기능

- **프로젝트별 트리뷰** - 프로젝트 → 모듈 → 그룹 → 엔드포인트 탐색
- **실시간 미리보기** - 엔드포인트 클릭 시 상세 정보 표시
- **문서 생성** - 버튼 클릭으로 문서 생성
- **파일 감시** - `.api.txt` 변경 시 자동 새로고침

### 트리뷰 구조

```
API Spec
├── my-project
│   └── user
│       ├── User Management
│       │   ├── GET /users
│       │   ├── GET /users/{id}
│       │   ├── POST /users
│       │   └── DELETE /users/{id}
│       └── Authentication
│           ├── POST /auth/login
│           └── GET /auth/me
└── another-project
    └── product
        └── Product Management
            ├── GET /products
            └── POST /products
```

### 수동 설치

```bash
code --install-extension node_modules/api-spec-editor/extension/api-spec-viewer-1.0.0.vsix
```

---

## 생성되는 문서

### OpenAPI 3.0 (YAML/JSON)

Swagger UI, Postman, Insomnia 등에서 바로 사용 가능한 표준 OpenAPI 문서

### Markdown

API 문서를 Markdown 형식으로 생성하여 GitHub, GitLab, Notion 등에서 바로 열람 가능

---

## 워크플로우 예시

### API-First 개발

```bash
# 1. 스펙 파일 작성
npx api-spec init user
# api-specs/user.api.txt 편집

# 2. 스펙 검증
npx api-spec validate user

# 3. 문서 생성
npx api-spec generate user

# 4. 팀 리뷰
# api-docs/user.openapi.yaml 공유

# 5. 코드 구현
# 스펙에 맞춰 API 개발
```

---

## License