# API Explorer 상세 설계서

> **문서 버전**: 1.0
> **작성일**: 2025-12-17
> **대상 프로젝트**: mng (Plain Laravel + Blade + Tailwind)

---

## 1. 개요

### 1.1 목적
Swagger UI의 한계를 극복하고, 개발팀의 API 관리 효율성을 높이기 위한 커스텀 API Explorer 개발

### 1.2 Swagger 대비 개선점

| 기능 | Swagger UI | API Explorer |
|------|------------|--------------|
| 검색 | 엔드포인트명만 | 풀텍스트 (설명, 파라미터 포함) |
| 그룹핑 | 태그만 | 태그 + 상태 + 메서드 + 커스텀 |
| 즐겨찾기 | ❌ | ⭐ 사용자별 북마크 |
| 요청 템플릿 | ❌ | 💾 저장/공유 가능 |
| 히스토리 | ❌ | 📋 최근 요청 + 재실행 |
| 환경 전환 | 수동 | 🔄 원클릭 전환 |

### 1.3 기술 스택
- **Backend**: Laravel 12 (mng 프로젝트)
- **Frontend**: Blade + Tailwind CSS + HTMX
- **Data Source**: OpenAPI 3.0 JSON (`api/storage/api-docs/api-docs.json`)
- **HTTP Client**: Guzzle (서버사이드 프록시)

---

## 2. 시스템 아키텍처

### 2.1 전체 구조

```
┌─────────────────────────────────────────────────────────────────┐
│                        API Explorer (mng)                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │   Browser    │───>│   Laravel    │───>│   API Server     │  │
│  │   (HTMX)     │<───│   (Proxy)    │<───│   (api/)         │  │
│  └──────────────┘    └──────────────┘    └──────────────────┘  │
│         │                   │                                    │
│         │            ┌──────┴──────┐                            │
│         │            │             │                             │
│         │      ┌─────┴─────┐ ┌─────┴─────┐                      │
│         │      │  SQLite   │ │  OpenAPI  │                      │
│         │      │  (Local)  │ │   JSON    │                      │
│         │      └───────────┘ └───────────┘                      │
│         │                                                        │
│  ┌──────┴───────────────────────────────────────────────────┐  │
│  │                     Local Storage                          │  │
│  │  • 환경 설정 (현재 서버)                                    │  │
│  │  • UI 상태 (패널 크기, 필터)                               │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 데이터 흐름

```
1. OpenAPI 파싱
   api-docs.json ──> OpenApiParserService ──> 구조화된 API 데이터

2. API 요청 프록시
   Browser ──HTMX──> ApiExplorerController ──Guzzle──> API Server

3. 사용자 데이터 (즐겨찾기, 템플릿, 히스토리)
   Browser ──> ApiExplorerController ──> SQLite/MySQL
```

---

## 3. 디렉토리 구조

```
mng/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── DevTools/
│   │           └── ApiExplorerController.php
│   ├── Services/
│   │   └── ApiExplorer/
│   │       ├── OpenApiParserService.php      # OpenAPI JSON 파싱
│   │       ├── ApiRequestService.php         # API 호출 프록시
│   │       └── ApiExplorerService.php        # 비즈니스 로직 통합
│   └── Models/
│       └── DevTools/
│           ├── ApiBookmark.php               # 즐겨찾기
│           ├── ApiTemplate.php               # 요청 템플릿
│           └── ApiHistory.php                # 요청 히스토리
│
├── database/
│   └── migrations/
│       └── 2024_xx_xx_create_api_explorer_tables.php
│
├── resources/
│   └── views/
│       └── dev-tools/
│           └── api-explorer/
│               ├── index.blade.php           # 메인 레이아웃
│               ├── partials/
│               │   ├── sidebar.blade.php     # API 목록 + 검색/필터
│               │   ├── endpoint-item.blade.php  # 개별 엔드포인트 항목
│               │   ├── request-panel.blade.php  # 요청 작성 패널
│               │   ├── response-panel.blade.php # 응답 표시 패널
│               │   ├── template-modal.blade.php # 템플릿 저장/불러오기
│               │   └── history-drawer.blade.php # 히스토리 서랍
│               └── components/
│                   ├── method-badge.blade.php   # HTTP 메서드 배지
│                   ├── param-input.blade.php    # 파라미터 입력 필드
│                   ├── json-editor.blade.php    # JSON 편집기
│                   └── json-viewer.blade.php    # JSON 뷰어 (트리/Raw)
│
├── routes/
│   └── web.php                               # 라우트 추가
│
└── config/
    └── api-explorer.php                      # 설정 파일
```

---

## 4. 데이터베이스 스키마

### 4.1 ERD

```
┌─────────────────────┐     ┌─────────────────────┐
│   api_bookmarks     │     │   api_templates     │
├─────────────────────┤     ├─────────────────────┤
│ id (PK)             │     │ id (PK)             │
│ user_id (FK)        │     │ user_id (FK)        │
│ endpoint            │     │ endpoint            │
│ method              │     │ method              │
│ display_name        │     │ name                │
│ display_order       │     │ description         │
│ color               │     │ headers (JSON)      │
│ created_at          │     │ path_params (JSON)  │
│ updated_at          │     │ query_params (JSON) │
└─────────────────────┘     │ body (JSON)         │
                            │ is_shared           │
                            │ created_at          │
                            │ updated_at          │
                            └─────────────────────┘

┌─────────────────────┐     ┌─────────────────────┐
│   api_histories     │     │  api_environments   │
├─────────────────────┤     ├─────────────────────┤
│ id (PK)             │     │ id (PK)             │
│ user_id (FK)        │     │ user_id (FK)        │
│ endpoint            │     │ name                │
│ method              │     │ base_url            │
│ request_headers     │     │ api_key             │
│ request_body        │     │ auth_token          │
│ response_status     │     │ variables (JSON)    │
│ response_headers    │     │ is_default          │
│ response_body       │     │ created_at          │
│ duration_ms         │     │ updated_at          │
│ environment         │     └─────────────────────┘
│ created_at          │
└─────────────────────┘
```

### 4.2 마이그레이션

```php
// api_bookmarks
Schema::create('api_bookmarks', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->string('endpoint', 500);
    $table->string('method', 10);
    $table->string('display_name', 100)->nullable();
    $table->integer('display_order')->default(0);
    $table->string('color', 20)->nullable();
    $table->timestamps();

    $table->unique(['user_id', 'endpoint', 'method']);
    $table->index('user_id');
});

// api_templates
Schema::create('api_templates', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->string('endpoint', 500);
    $table->string('method', 10);
    $table->string('name', 100);
    $table->text('description')->nullable();
    $table->json('headers')->nullable();
    $table->json('path_params')->nullable();
    $table->json('query_params')->nullable();
    $table->json('body')->nullable();
    $table->boolean('is_shared')->default(false);
    $table->timestamps();

    $table->index(['user_id', 'endpoint', 'method']);
    $table->index('is_shared');
});

// api_histories
Schema::create('api_histories', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->string('endpoint', 500);
    $table->string('method', 10);
    $table->json('request_headers')->nullable();
    $table->json('request_body')->nullable();
    $table->integer('response_status');
    $table->json('response_headers')->nullable();
    $table->longText('response_body')->nullable();
    $table->integer('duration_ms');
    $table->string('environment', 50);
    $table->timestamp('created_at');

    $table->index(['user_id', 'created_at']);
    $table->index(['endpoint', 'method']);
});

// api_environments
Schema::create('api_environments', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->string('name', 50);
    $table->string('base_url', 500);
    $table->string('api_key', 500)->nullable();
    $table->text('auth_token')->nullable();
    $table->json('variables')->nullable();
    $table->boolean('is_default')->default(false);
    $table->timestamps();

    $table->index('user_id');
});
```

---

## 5. UI 설계

### 5.1 메인 레이아웃 (3-Panel)

```
┌────────────────────────────────────────────────────────────────────────────┐
│ 🔍 Search...          │ [로컬 ▼] │ 📋 History │ ⚙️ Settings                │
├────────────────────────────────────────────────────────────────────────────┤
│                       │                          │                          │
│   API Sidebar         │    Request Panel         │    Response Panel        │
│   (resizable)         │    (resizable)           │    (resizable)           │
│                       │                          │                          │
│ ┌───────────────────┐ │ ┌──────────────────────┐ │ ┌──────────────────────┐ │
│ │ 🔍 필터            │ │ │ POST /api/v1/login   │ │ │ Status: 200 OK ✓    │ │
│ │ [GET][POST][PUT]  │ │ │                      │ │ │ Time: 45ms           │ │
│ │ [DELETE][PATCH]   │ │ │ ┌─ Headers ─────────┐│ │ │                      │ │
│ │                   │ │ │ │ Authorization: [] ││ │ │ ┌─ Headers ─────────┐│ │
│ │ ⭐ 즐겨찾기 (3)    │ │ │ │ Content-Type: [] ││ │ │ │ content-type: ... ││ │
│ │  POST login       │ │ │ └──────────────────┘│ │ │ │ x-request-id: ... ││ │
│ │  GET users        │ │ │                      │ │ │ └──────────────────┘│ │
│ │  POST logout      │ │ │ ┌─ Path Params ────┐│ │ │                      │ │
│ │                   │ │ │ │ (none)           ││ │ │ ┌─ Body ─────────────┐│ │
│ │ 📁 Auth           │ │ │ └──────────────────┘│ │ │ │ {                  ││ │
│ │  ├ POST login     │ │ │                      │ │ │ │   "success": true, ││ │
│ │  ├ POST logout    │ │ │ ┌─ Query Params ───┐│ │ │ │   "data": {        ││ │
│ │  └ GET me         │ │ │ │ (none)           ││ │ │ │     "token": "..."  ││ │
│ │                   │ │ │ └──────────────────┘│ │ │ │   }                ││ │
│ │ 📁 Users          │ │ │                      │ │ │ │ }                  ││ │
│ │  ├ GET list       │ │ │ ┌─ Body (JSON) ────┐│ │ │ └──────────────────┘│ │
│ │  ├ GET {id}       │ │ │ │ {                ││ │ │                      │ │
│ │  ├ POST create    │ │ │ │   "user_id": "", ││ │ │ [Raw] [Pretty] [Tree]│ │
│ │  ├ PUT {id}       │ │ │ │   "user_pwd": "" ││ │ │                      │ │
│ │  └ DELETE {id}    │ │ │ │ }                ││ │ │ [📋 Copy] [💾 Save]  │ │
│ │                   │ │ │ └──────────────────┘│ │ │                      │ │
│ │ 📁 Products       │ │ │                      │ │ └──────────────────────┘ │
│ │  └ ...            │ │ │ [📋 템플릿] [▶ 실행]│ │                          │
│ └───────────────────┘ │ └──────────────────────┘ │                          │
│                       │                          │                          │
└────────────────────────────────────────────────────────────────────────────┘
```

### 5.2 컬러 스킴

```css
/* HTTP 메서드 배지 */
.method-get    { @apply bg-green-100 text-green-800; }
.method-post   { @apply bg-blue-100 text-blue-800; }
.method-put    { @apply bg-yellow-100 text-yellow-800; }
.method-patch  { @apply bg-orange-100 text-orange-800; }
.method-delete { @apply bg-red-100 text-red-800; }

/* 상태 코드 */
.status-2xx { @apply text-green-600; }  /* 성공 */
.status-3xx { @apply text-blue-600; }   /* 리다이렉트 */
.status-4xx { @apply text-yellow-600; } /* 클라이언트 에러 */
.status-5xx { @apply text-red-600; }    /* 서버 에러 */
```

### 5.3 반응형 동작

| 화면 크기 | 동작 |
|-----------|------|
| Desktop (≥1280px) | 3-Panel 표시 |
| Tablet (768-1279px) | 2-Panel (사이드바 접힘 가능) |
| Mobile (<768px) | 1-Panel (탭 전환) |

---

## 6. API 설계

### 6.1 라우트 정의

```php
// routes/web.php
Route::prefix('dev-tools/api-explorer')
    ->middleware(['auth'])
    ->name('api-explorer.')
    ->group(function () {
        // 메인 페이지
        Route::get('/', [ApiExplorerController::class, 'index'])->name('index');

        // API 목록 (HTMX partial)
        Route::get('/endpoints', [ApiExplorerController::class, 'endpoints'])->name('endpoints');
        Route::get('/endpoints/{operationId}', [ApiExplorerController::class, 'endpoint'])->name('endpoint');

        // API 실행 (프록시)
        Route::post('/execute', [ApiExplorerController::class, 'execute'])->name('execute');

        // 즐겨찾기
        Route::get('/bookmarks', [ApiExplorerController::class, 'bookmarks'])->name('bookmarks');
        Route::post('/bookmarks', [ApiExplorerController::class, 'addBookmark'])->name('bookmarks.add');
        Route::delete('/bookmarks/{id}', [ApiExplorerController::class, 'removeBookmark'])->name('bookmarks.remove');
        Route::put('/bookmarks/reorder', [ApiExplorerController::class, 'reorderBookmarks'])->name('bookmarks.reorder');

        // 템플릿
        Route::get('/templates', [ApiExplorerController::class, 'templates'])->name('templates');
        Route::get('/templates/{endpoint}', [ApiExplorerController::class, 'templatesForEndpoint'])->name('templates.endpoint');
        Route::post('/templates', [ApiExplorerController::class, 'saveTemplate'])->name('templates.save');
        Route::delete('/templates/{id}', [ApiExplorerController::class, 'deleteTemplate'])->name('templates.delete');

        // 히스토리
        Route::get('/history', [ApiExplorerController::class, 'history'])->name('history');
        Route::delete('/history', [ApiExplorerController::class, 'clearHistory'])->name('history.clear');
        Route::post('/history/{id}/replay', [ApiExplorerController::class, 'replayHistory'])->name('history.replay');

        // 환경
        Route::get('/environments', [ApiExplorerController::class, 'environments'])->name('environments');
        Route::post('/environments', [ApiExplorerController::class, 'saveEnvironment'])->name('environments.save');
        Route::delete('/environments/{id}', [ApiExplorerController::class, 'deleteEnvironment'])->name('environments.delete');
        Route::post('/environments/{id}/default', [ApiExplorerController::class, 'setDefaultEnvironment'])->name('environments.default');
    });
```

### 6.2 Controller 메서드 시그니처

```php
class ApiExplorerController extends Controller
{
    public function __construct(
        private OpenApiParserService $parser,
        private ApiRequestService $requester,
        private ApiExplorerService $explorer
    ) {}

    // GET /dev-tools/api-explorer
    public function index(): View

    // GET /dev-tools/api-explorer/endpoints?search=&tags[]=&methods[]=
    public function endpoints(Request $request): View  // HTMX partial

    // GET /dev-tools/api-explorer/endpoints/{operationId}
    public function endpoint(string $operationId): View  // HTMX partial

    // POST /dev-tools/api-explorer/execute
    public function execute(ExecuteApiRequest $request): JsonResponse

    // Bookmarks CRUD...
    // Templates CRUD...
    // History CRUD...
    // Environments CRUD...
}
```

### 6.3 Service 클래스

```php
// OpenApiParserService - OpenAPI JSON 파싱
class OpenApiParserService
{
    public function parse(): array;                           // 전체 스펙 파싱
    public function getEndpoints(): Collection;               // 엔드포인트 목록
    public function getEndpoint(string $operationId): ?array; // 단일 엔드포인트
    public function getTags(): array;                         // 태그 목록
    public function search(string $query): Collection;        // 검색
    public function filter(array $filters): Collection;       // 필터링
}

// ApiRequestService - API 호출 프록시
class ApiRequestService
{
    public function execute(
        string $method,
        string $url,
        array $headers = [],
        array $query = [],
        ?array $body = null
    ): ApiResponse;
}

// ApiExplorerService - 비즈니스 로직 통합
class ApiExplorerService
{
    // Bookmark operations
    public function getBookmarks(int $userId): Collection;
    public function addBookmark(int $userId, array $data): ApiBookmark;
    public function removeBookmark(int $bookmarkId): void;

    // Template operations
    public function getTemplates(int $userId, ?string $endpoint = null): Collection;
    public function saveTemplate(int $userId, array $data): ApiTemplate;
    public function deleteTemplate(int $templateId): void;

    // History operations
    public function logRequest(int $userId, array $data): ApiHistory;
    public function getHistory(int $userId, int $limit = 50): Collection;
    public function clearHistory(int $userId): void;

    // Environment operations
    public function getEnvironments(int $userId): Collection;
    public function saveEnvironment(int $userId, array $data): ApiEnvironment;
}
```

---

## 7. 핵심 기능 상세

### 7.1 스마트 검색

```php
// 검색 대상 필드
$searchFields = [
    'endpoint',      // /api/v1/users
    'summary',       // "사용자 목록 조회"
    'description',   // 상세 설명
    'operationId',   // getUserList
    'parameters.*.name',        // 파라미터명
    'parameters.*.description', // 파라미터 설명
    'tags',          // 태그
];

// 검색 알고리즘
1. 정확히 일치 → 최상위
2. 시작 부분 일치 → 높은 순위
3. 포함 → 일반 순위
4. Fuzzy 매칭 → 낮은 순위 (선택적)
```

### 7.2 필터링 옵션

```php
$filters = [
    'methods' => ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
    'tags' => ['Auth', 'Users', 'Products', ...],
    'status' => ['stable', 'beta', 'deprecated'],
    'hasBody' => true|false,
    'requiresAuth' => true|false,
];
```

### 7.3 요청 템플릿 시스템

```json
// 템플릿 저장 형식
{
    "name": "로그인 테스트",
    "description": "테스트 계정으로 로그인",
    "endpoint": "/api/v1/login",
    "method": "POST",
    "headers": {
        "X-API-KEY": "{{API_KEY}}"
    },
    "body": {
        "user_id": "test",
        "user_pwd": "testpass"
    },
    "is_shared": false
}
```

### 7.4 환경 변수 시스템

```json
// 환경 설정 형식
{
    "name": "로컬",
    "base_url": "http://api.sam.kr",
    "api_key": "your-api-key",
    "auth_token": null,
    "variables": {
        "TENANT_ID": "1",
        "USER_ID": "test"
    }
}

// 변수 치환: {{VARIABLE_NAME}}
// 예: "Authorization": "Bearer {{AUTH_TOKEN}}"
```

---

## 8. HTMX 통합

### 8.1 주요 HTMX 패턴

```html
<!-- 엔드포인트 목록 갱신 -->
<div id="endpoint-list"
     hx-get="/dev-tools/api-explorer/endpoints"
     hx-trigger="load, search"
     hx-swap="innerHTML">
</div>

<!-- 검색 입력 -->
<input type="text"
       name="search"
       hx-get="/dev-tools/api-explorer/endpoints"
       hx-trigger="keyup changed delay:300ms"
       hx-target="#endpoint-list"
       hx-include="[name='methods[]'], [name='tags[]']">

<!-- 엔드포인트 선택 -->
<button hx-get="/dev-tools/api-explorer/endpoints/{{ $operationId }}"
        hx-target="#request-panel"
        hx-swap="innerHTML">
</button>

<!-- API 실행 -->
<form hx-post="/dev-tools/api-explorer/execute"
      hx-target="#response-panel"
      hx-indicator="#loading-spinner">
</form>

<!-- 즐겨찾기 토글 -->
<button hx-post="/dev-tools/api-explorer/bookmarks"
        hx-vals='{"endpoint": "{{ $endpoint }}", "method": "{{ $method }}"}'
        hx-swap="outerHTML">
    ⭐
</button>
```

### 8.2 OOB (Out-of-Band) 업데이트

```html
<!-- 응답 후 히스토리 자동 갱신 -->
<div id="history-count" hx-swap-oob="true">
    {{ $historyCount }}
</div>
```

---

## 9. 보안 고려사항

### 9.1 접근 제어
- mng 프로젝트 로그인 필수 (`auth` 미들웨어)
- 개발 환경에서만 접근 가능 (선택적)
- API Key/Token은 서버사이드에서만 관리

### 9.2 민감 정보 처리
- 환경 설정의 API Key는 암호화 저장
- 히스토리에서 민감 헤더 마스킹 옵션
- 공유 템플릿에서 인증 정보 자동 제외

### 9.3 프록시 보안
- 허용된 base_url만 프록시 가능 (화이트리스트)
- 요청 크기 제한 (body 최대 1MB)
- 타임아웃 설정 (30초)

---

## 10. 구현 로드맵

### Phase 1: 기본 구조 (3-4일)
- [ ] 디렉토리 구조 생성
- [ ] 마이그레이션 파일 작성
- [ ] OpenApiParserService 구현
- [ ] 기본 UI 레이아웃 (3-Panel)
- [ ] 엔드포인트 목록 표시

### Phase 2: 검색/필터/요청 (3일)
- [ ] 풀텍스트 검색 구현
- [ ] 메서드/태그 필터링
- [ ] 요청 패널 UI
- [ ] ApiRequestService (프록시)
- [ ] 응답 표시 (JSON Viewer)

### Phase 3: 사용자 데이터 (3일)
- [ ] 즐겨찾기 CRUD
- [ ] 템플릿 저장/불러오기
- [ ] 히스토리 기록/재실행
- [ ] 드래그&드롭 정렬

### Phase 4: 환경/고급 기능 (2-3일)
- [ ] 환경 관리 UI
- [ ] 변수 치환 시스템
- [ ] 키보드 단축키
- [ ] UI 폴리싱
- [ ] 반응형 최적화

### Phase 5: 테스트/배포 (2일)
- [ ] 기능 테스트
- [ ] 성능 최적화
- [ ] 문서화
- [ ] 배포

**예상 총 기간: 13-15일**

---

## 11. 향후 확장 가능성

### 11.1 추가 기능 후보
- **Mock 서버**: 테스트용 가짜 응답 생성
- **API 비교**: 두 환경 간 응답 비교
- **자동 테스트**: 저장된 템플릿 일괄 실행
- **변경 감지**: OpenAPI 스펙 변경 알림
- **문서 생성**: Markdown/PDF 문서 자동 생성

### 11.2 통합 가능성
- **CI/CD**: API 테스트 자동화
- **Slack/Teams**: 알림 연동
- **Postman**: 컬렉션 import/export

---

## 12. 참고 자료

### 12.1 유사 도구
- [Scalar](https://scalar.com/) - 현대적 API 문서
- [Stoplight](https://stoplight.io/) - API 설계 도구
- [Insomnia](https://insomnia.rest/) - API 클라이언트

### 12.2 기술 문서
- [OpenAPI 3.0 Specification](https://spec.openapis.org/oas/v3.0.3)
- [HTMX Documentation](https://htmx.org/docs/)
- [Laravel HTTP Client](https://laravel.com/docs/http-client)