api-spec-editor

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


왜 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
`

---

스펙 파일 작성법

$3

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

---

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

---

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

$3

| 문법 | 설명 | 예시 |
|------|------|------|
| [모듈명] | 모듈 헤더 | [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 |

$3

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

`
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
`

$3

#### 인라인 방식

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

#### 하위 depth 방식

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

$3

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

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

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

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

---

예시

$3

`
[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
`

$3

`
[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

`
[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
`

$3

`
[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 명령어

$3

새 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 생성
`

$3

문서 생성

`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만 생성
`

$3

스펙 검증

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

$3

엔드포인트 목록

`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 확장이 자동으로 설치됩니다.

$3

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

$3

`
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
`

$3

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

---

생성되는 문서

$3

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

$3

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

---

워크플로우 예시

$3

`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