MapleStory Open API

Nexon MapleStory Open API (https://openapi.nexon.com/ko/game/maplestory) TypeScript 클라이언트 패키지

설치

pnpm install

API 문서 크롤러

Swagger UI 기반의 MapleStory Open API 문서를 크롤링하여 JSON 스키마와 TypeScript 타입을 자동 생성합니다.

사용법

# 전체 카테고리 크롤링 (기본 모드)
pnpm crawl

# 상세 모드 (파라미터, 응답 스키마 포함)
pnpm crawl --detailed

# 특정 카테고리만 크롤링
pnpm crawl -c character -c ranking --detailed

# JSON만 생성
pnpm crawl --detailed --json-only

# TypeScript 타입만 생성
pnpm crawl --detailed --types-only

# 브라우저 표시 모드
pnpm crawl --detailed --no-headless

# 드라이런 (파일 생성 없이 시뮬레이션)
pnpm crawl --dry-run

CLI 옵션

| 옵션 | 단축 | 설명 | |------|------|------| | --category | -c | 크롤링할 카테고리 지정 (복수 가능) | | --output | -o | 출력 디렉토리 (기본: ./output) | | --detailed | -d | 상세 모드 (파라미터/응답 스키마 추출) | | --json-only | | JSON 파일만 생성 | | --types-only | | TypeScript 타입만 생성 | | --headless | | 헤드리스 브라우저 모드 (기본값) | | --no-headless | | 브라우저 창 표시 | | --timeout | -t | 타임아웃 (ms, 기본: 10000) | | --verbose | -v | 상세 로그 출력 | | --dry-run | | 시뮬레이션 모드 |

지원 카테고리

| 카테고리 | ID | 설명 | |----------|----|----| | character | 14 | 캐릭터 정보 조회 | | union | 15 | 유니온 정보 조회 | | guild | 16 | 길드 정보 조회 | | history | 17 | 확률 정보 조회 (스타포스, 잠재능력, 큐브) | | ranking | 18 | 랭킹 정보 조회 | | notice | 24 | 공지 정보 조회 |

출력 구조

output/
├── json/
│   ├── character.json
│   ├── union.json
│   ├── guild.json
│   ├── history.json
│   ├── ranking.json
│   └── notice.json
└── types/
    ├── index.ts
    ├── common.types.ts
    ├── character.types.ts
    ├── union.types.ts
    ├── guild.types.ts
    ├── history.types.ts
    ├── ranking.types.ts
    └── notice.types.ts

생성된 타입 사용 예시

import type {
  CharacterBasicResponse,
  CharacterBasicParams,
  RankingOverallResponse,
  RankingOverallParams,
} from './output/types';

// 캐릭터 기본 정보 조회
const params: CharacterBasicParams = {
  ocid: 'character-ocid',
  date: '2024-12-24',
};

// 응답 타입
const response: CharacterBasicResponse = {
  character_name: '캐릭터명',
  world_name: '스카니아',
  character_class: '아크메이지(불,독)',
  character_level: 275,
  // ...
};

개발

# 빌드
pnpm build

# 테스트
pnpm test

# 린트 & 포맷
pnpm biome check . --write

기술 스택

• Package Manager: pnpm
• HTTP Client: ky
• Build Tool: tsup
• Browser Automation: Playwright
• Linter/Formatter: Biome
• Test Framework: Vitest
• Language: TypeScript

API 참고

• Base URL: https://open.api.nexon.com
• 인증: 모든 요청에 x-nxopen-api-key 헤더 필요
• Rate Limits:
  • Development: 5 req/sec, 1,000 req/day
  • Production: 500 req/sec, 20,000,000 req/day

라이선스

MIT