mock-fried 1.0.0

package/README.md

@@ -0,0 +1,229 @@
+# Mock-Fried
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Nuxt 3 Mock API Module - OpenAPI & Protobuf RPC Mock Server
+
+## Features
+
+- **OpenAPI Mock Server** - OpenAPI 스펙 기반 자동 Mock 응답 생성
+- **Protobuf RPC Mock** - Proto 파일 기반 gRPC-style RPC Mock
+- **API Explorer** - Swagger UI 스타일의 인터랙티브 API 테스트 UI
+- **Type-Safe Client** - `$api` 클라이언트로 타입 안전한 API 호출
+- **Zero Config** - 스펙 파일만 있으면 즉시 사용 가능
+
+## Quick Setup
+
+```bash
+# npm
+npm install mock-fried
+
+# yarn
+yarn add mock-fried
+
+# pnpm
+pnpm add mock-fried
+```
+
+`nuxt.config.ts`에 모듈 추가:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['mock-fried'],
+
+  mock: {
+    enable: true,
+    prefix: '/mock',
+    openapi: './mocks/openapi.yaml',  // OpenAPI 스펙 경로
+    proto: './mocks/example.proto',    // Proto 파일 경로
+  },
+})
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enable` | `boolean` | `true` | Mock 기능 활성화 |
+| `prefix` | `string` | `'/mock'` | API 라우트 prefix |
+| `openapi` | `string \| object` | - | OpenAPI 스펙 파일 경로 또는 클라이언트 패키지 설정 |
+| `proto` | `string` | - | Proto 파일 경로 |
+
+### OpenAPI 설정 옵션
+
+**1. 스펙 파일 직접 사용:**
+
+```typescript
+mock: {
+  // 상대 경로
+  openapi: './mocks/openapi.yaml',
+
+  // 절대 경로
+  openapi: '/path/to/openapi.yaml',
+}
+```
+
+**2. 생성된 클라이언트 패키지 사용 (권장):**
+
+```typescript
+mock: {
+  // openapi-generator로 생성된 TypeScript 클라이언트 패키지
+  openapi: {
+    package: '@your-org/api-client',
+    apisDir: 'src/apis',      // optional, default: 'src/apis'
+    modelsDir: 'src/models',  // optional, default: 'src/models'
+  },
+}
+```
+
+생성된 클라이언트 패키지를 사용하면:
+
+- 정확한 타입 기반 Mock 데이터 생성
+- 실제 API 응답 구조와 일치하는 Mock 응답
+- snake_case/camelCase JSON 키 변환 자동 처리
+
+## Usage
+
+### REST API (OpenAPI)
+
+```typescript
+const { $api } = useNuxtApp()
+
+// GET 요청
+const users = await $api.rest('/users')
+
+// Path 파라미터
+const user = await $api.rest('/users/1')
+
+// Query 파라미터
+const products = await $api.rest('/products', {
+  params: { category: 'electronics', limit: 10 }
+})
+
+// POST 요청
+const newUser = await $api.rest('/users', {
+  method: 'POST',
+  body: { name: 'John', email: 'john@example.com' }
+})
+```
+
+### RPC (Protobuf)
+
+```typescript
+const { $api } = useNuxtApp()
+
+// 명시적 RPC 호출
+const user = await $api.rpc('UserService', 'GetUser', { id: 1 })
+
+// 동적 서비스 접근
+const user = await $api.UserService.GetUser({ id: 1 })
+const products = await $api.ProductService.ListProducts({ page: 1, limit: 10 })
+```
+
+### API Schema 조회
+
+```typescript
+const { $api } = useNuxtApp()
+
+// 전체 스키마 조회
+const schema = await $api.getSchema()
+// { openapi: {...}, rpc: {...} }
+```
+
+## API Explorer
+
+모듈에 포함된 API Explorer 컴포넌트로 Swagger UI 스타일의 인터페이스 제공:
+
+```vue
+<template>
+  <MockApiExplorer
+    title="My API Explorer"
+    description="Interactive API Testing"
+  />
+</template>
+```
+
+### 포함된 컴포넌트
+
+| Component | Description |
+|-----------|-------------|
+| `<MockApiExplorer>` | 메인 API 탐색기 |
+| `<MockEndpointCard>` | REST 엔드포인트 카드 |
+| `<MockRpcMethodCard>` | RPC 메서드 카드 |
+| `<MockResponseViewer>` | 응답 뷰어 모달 |
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/mock/__schema` | GET | API 스키마 메타데이터 |
+| `/mock/**` | * | OpenAPI Mock 핸들러 |
+| `/mock/rpc/:service/:method` | POST | RPC Mock 핸들러 |
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Generate type stubs
+yarn dev:prepare
+
+# Develop with OpenAPI playground
+yarn dev:openapi
+
+# Develop with Proto playground
+yarn dev:proto
+
+# Run ESLint
+yarn lint
+yarn lint:fix
+
+# Format with Prettier
+yarn format
+
+# Run tests
+yarn test
+yarn test:watch
+
+# Type check
+yarn test:types
+```
+
+## Project Structure
+
+```
+mock-fried/
+├── src/
+│   ├── module.ts              # 모듈 엔트리
+│   ├── types.ts               # 타입 정의
+│   └── runtime/
+│       ├── plugin.ts          # $api 클라이언트 플러그인
+│       ├── composables/       # useApi composable
+│       ├── components/        # API Explorer 컴포넌트
+│       └── server/
+│           ├── handlers/      # Nitro 서버 핸들러
+│           └── utils/         # Mock 데이터 생성 유틸
+├── playground-openapi/        # OpenAPI 테스트 환경
+└── playground-proto/          # Proto 테스트 환경
+```
+
+## License
+
+[MIT License](./LICENSE)
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/mock-fried/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/mock-fried
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/mock-fried.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/mock-fried
+
+[license-src]: https://img.shields.io/npm/l/mock-fried.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/mock-fried
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,125 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+/**
+ * Pagination 설정
+ */
+interface MockPaginationConfig {
+    /**
+     * 캐싱 활성화
+     * @default true
+     */
+    cache?: boolean;
+    /**
+     * 캐시 TTL (밀리초)
+     * @default 1800000 (30분)
+     */
+    cacheTTL?: number;
+    /**
+     * 기본 총 아이템 수
+     * @default 100
+     */
+    defaultTotal?: number;
+    /**
+     * 기본 페이지 크기
+     * @default 20
+     */
+    defaultLimit?: number;
+    /**
+     * 응답에 snapshotId 포함 여부
+     * @default false
+     */
+    includeSnapshotId?: boolean;
+}
+/**
+ * Cursor 설정
+ */
+interface MockCursorConfig {
+    /**
+     * 만료 활성화
+     * @default true
+     */
+    enableExpiry?: boolean;
+    /**
+     * Cursor TTL (밀리초)
+     * @default 3600000 (1시간)
+     */
+    cursorTTL?: number;
+    /**
+     * 정렬 정보 포함 여부
+     * @default false
+     */
+    includeSortInfo?: boolean;
+}
+/**
+ * 응답 포맷 타입
+ * - 'auto': 기존 동작 유지 (스키마 기반 자동)
+ * - 'standardized': 표준화된 응답 형식
+ */
+type MockResponseFormat = 'auto' | 'standardized';
+/**
+ * Mock Module Options
+ * nuxt.config.ts에서 mock 키로 설정
+ */
+interface MockModuleOptions {
+    /**
+     * Mock 기능 활성화 여부
+     * @default true
+     */
+    enable: boolean;
+    /**
+     * Mock API 라우트 prefix
+     * @default '/mock'
+     */
+    prefix: string;
+    /**
+     * OpenAPI 설정
+     * - 문자열: 스펙 파일 경로 (yaml/json)
+     * - 객체: 생성된 클라이언트 패키지 설정
+     * @example './mocks/openapi.yaml'
+     * @example { package: '@org/openapi-client' }
+     */
+    openapi?: string | OpenApiClientConfig;
+    /**
+     * Proto 파일 또는 디렉토리 경로 (상대 경로)
+     * @example './mocks/example.proto' 또는 './mocks'
+     */
+    proto?: string;
+    /**
+     * Pagination 설정
+     */
+    pagination?: MockPaginationConfig;
+    /**
+     * Cursor 설정
+     */
+    cursor?: MockCursorConfig;
+    /**
+     * 응답 포맷
+     * @default 'auto'
+     */
+    responseFormat?: MockResponseFormat;
+}
+/**
+ * OpenAPI 클라이언트 패키지 설정
+ */
+interface OpenApiClientConfig {
+    /**
+     * npm 패키지명
+     * @example '@ptcorp-eosikahair/openapi'
+     */
+    package: string;
+    /**
+     * API 파일 디렉토리 (패키지 루트 기준)
+     * @default 'src/apis'
+     */
+    apisDir?: string;
+    /**
+     * Model 파일 디렉토리 (패키지 루트 기준)
+     * @default 'src/models'
+     */
+    modelsDir?: string;
+}
+
+declare const _default: _nuxt_schema.NuxtModule<MockModuleOptions, MockModuleOptions, false>;
+
+export { _default as default };
+export type { MockModuleOptions, OpenApiClientConfig };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "mock-fried",
+  "configKey": "mock",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,160 @@
+import { defineNuxtModule, createResolver, useLogger, addServerHandler, addPlugin, addImports, addComponentsDir } from '@nuxt/kit';
+import { normalize, resolve } from 'pathe';
+import { createRequire } from 'node:module';
+
+function parsePackagePath(specPath) {
+  if (specPath.startsWith("@")) {
+    const parts = specPath.split("/");
+    if (parts.length >= 2) {
+      const pkg = `${parts[0]}/${parts[1]}`;
+      const subpath = parts.slice(2).join("/");
+      return { pkg, subpath: subpath || void 0 };
+    }
+  }
+  const slashIndex = specPath.indexOf("/");
+  if (slashIndex > 0) {
+    return {
+      pkg: specPath.slice(0, slashIndex),
+      subpath: specPath.slice(slashIndex + 1)
+    };
+  }
+  return { pkg: specPath };
+}
+function resolvePackagePath(specPath, rootDir, defaultFiles = []) {
+  if (specPath.startsWith("./") || specPath.startsWith("../")) {
+    return normalize(resolve(rootDir, specPath));
+  }
+  if (specPath.startsWith("/") || /^[a-z]:/i.test(specPath)) {
+    return normalize(specPath);
+  }
+  try {
+    const require = createRequire(rootDir + "/package.json");
+    const { pkg, subpath } = parsePackagePath(specPath);
+    const pkgJsonPath = require.resolve(`${pkg}/package.json`);
+    const pkgRoot = resolve(pkgJsonPath, "..");
+    if (subpath) {
+      return normalize(resolve(pkgRoot, subpath));
+    }
+    for (const file of defaultFiles) {
+      const filePath = resolve(pkgRoot, file);
+      return normalize(filePath);
+    }
+    const mainPath = require.resolve(pkg);
+    return normalize(mainPath);
+  } catch {
+    return normalize(resolve(rootDir, specPath));
+  }
+}
+function resolveOpenAPIPath(specPath, rootDir) {
+  return resolvePackagePath(specPath, rootDir, [
+    "openapi.yaml",
+    "openapi.yml",
+    "openapi.json",
+    "spec.yaml",
+    "spec.yml",
+    "spec.json",
+    "swagger.yaml",
+    "swagger.json"
+  ]);
+}
+function resolveProtoPath(specPath, rootDir) {
+  return resolvePackagePath(specPath, rootDir, [
+    "proto/index.proto",
+    "protos/index.proto",
+    "index.proto",
+    "main.proto",
+    "service.proto"
+  ]);
+}
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "mock-fried",
+    configKey: "mock",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    enable: true,
+    prefix: "/mock"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const logger = useLogger("mock-fried");
+    if (!options.enable) {
+      logger.info("Mock module is disabled");
+      return;
+    }
+    const rootDir = nuxt.options.rootDir;
+    const prefix = options.prefix || "/mock";
+    let openapiPath;
+    let clientPackagePath;
+    let clientPackageConfig;
+    if (options.openapi) {
+      if (typeof options.openapi === "string") {
+        openapiPath = resolveOpenAPIPath(options.openapi, rootDir);
+      } else {
+        clientPackageConfig = options.openapi;
+        try {
+          const require = createRequire(rootDir + "/package.json");
+          const pkgJsonPath = require.resolve(`${options.openapi.package}/package.json`);
+          clientPackagePath = normalize(resolve(pkgJsonPath, ".."));
+        } catch {
+          logger.warn(`Failed to resolve client package: ${options.openapi.package}`);
+        }
+      }
+    }
+    const protoPath = options.proto ? resolveProtoPath(options.proto, rootDir) : void 0;
+    nuxt.options.runtimeConfig.mock = {
+      enable: options.enable,
+      prefix,
+      openapiPath,
+      clientPackagePath,
+      clientPackageConfig,
+      protoPath,
+      pagination: options.pagination,
+      cursor: options.cursor,
+      responseFormat: options.responseFormat ?? "auto"
+    };
+    nuxt.options.runtimeConfig.public.mock = {
+      enable: options.enable,
+      prefix
+    };
+    addServerHandler({
+      route: `${prefix}/__schema`,
+      method: "get",
+      handler: resolver.resolve("./runtime/server/handlers/schema")
+    });
+    logger.info(`Schema handler registered at GET ${prefix}/__schema`);
+    if (protoPath) {
+      addServerHandler({
+        route: `${prefix}/rpc/:service/:method`,
+        method: "post",
+        handler: resolver.resolve("./runtime/server/handlers/rpc")
+      });
+      logger.info(`RPC mock handler registered at POST ${prefix}/rpc/:service/:method`);
+    }
+    if (openapiPath || clientPackagePath) {
+      addServerHandler({
+        route: `${prefix}/**`,
+        handler: resolver.resolve("./runtime/server/handlers/openapi")
+      });
+      logger.info(`OpenAPI mock handler registered at ${prefix}/**`);
+    }
+    addPlugin(resolver.resolve("./runtime/plugin"));
+    addImports({
+      name: "useApi",
+      from: resolver.resolve("./runtime/composables")
+    });
+    addComponentsDir({
+      path: resolver.resolve("./runtime/components"),
+      prefix: "Mock"
+    });
+    logger.success(`Mock module initialized with prefix: ${prefix}`);
+    if (openapiPath) logger.info(`  OpenAPI spec: ${openapiPath}`);
+    if (clientPackagePath) logger.info(`  Client package: ${clientPackageConfig?.package}`);
+    if (protoPath) logger.info(`  Proto path: ${protoPath}`);
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/components/ApiExplorer.d.vue.ts

@@ -0,0 +1,7 @@
+type __VLS_Props = {
+    title?: string;
+    description?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/ApiExplorer.vue

@@ -0,0 +1,168 @@
+<template>
+  <div class="api-explorer">
+    <header class="explorer-header">
+      <h1>{{ title }}</h1>
+      <p
+        v-if="description"
+        class="description"
+      >
+        {{ description }}
+      </p>
+    </header>
+
+    <div
+      v-if="loading"
+      class="loading"
+    >
+      Loading API schema...
+    </div>
+
+    <div
+      v-else-if="error"
+      class="error"
+    >
+      {{ error }}
+    </div>
+
+    <template v-else>
+      <!-- OpenAPI Section -->
+      <section
+        v-if="schema?.openapi"
+        class="api-section"
+      >
+        <h2 class="section-title">
+          <span class="badge rest">REST</span>
+          {{ schema.openapi.info.title }}
+          <span class="version">v{{ schema.openapi.info.version }}</span>
+        </h2>
+
+        <div class="endpoints">
+          <EndpointCard
+            v-for="endpoint in schema.openapi.paths"
+            :key="`${endpoint.method}-${endpoint.path}`"
+            :endpoint="endpoint"
+            type="rest"
+            @execute="executeRest"
+          />
+        </div>
+      </section>
+
+      <!-- RPC Section -->
+      <section
+        v-if="schema?.rpc"
+        class="api-section"
+      >
+        <h2 class="section-title">
+          <span class="badge rpc">RPC</span>
+          {{ schema.rpc.package || "Services" }}
+        </h2>
+
+        <div
+          v-for="service in schema.rpc.services"
+          :key="service.name"
+          class="service-group"
+        >
+          <h3 class="service-name">
+            {{ service.name }}
+          </h3>
+          <div class="endpoints">
+            <RpcMethodCard
+              v-for="method in service.methods"
+              :key="method.name"
+              :service="service.name"
+              :method="method"
+              @execute="executeRpc"
+            />
+          </div>
+        </div>
+      </section>
+    </template>
+
+    <!-- Response Modal -->
+    <ResponseViewer
+      v-if="response"
+      :response="response"
+      @close="response = null"
+    />
+  </div>
+</template>
+
+<script setup>
+import EndpointCard from "./EndpointCard.vue";
+import RpcMethodCard from "./RpcMethodCard.vue";
+import ResponseViewer from "./ResponseViewer.vue";
+defineProps({
+  title: { type: String, required: false },
+  description: { type: String, required: false }
+});
+const { $api } = useNuxtApp();
+const schema = ref(null);
+const loading = ref(true);
+const error = ref(null);
+const response = ref(null);
+onMounted(async () => {
+  try {
+    schema.value = await $api.getSchema();
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : "Failed to load schema";
+  } finally {
+    loading.value = false;
+  }
+});
+async function executeRest(params) {
+  const startTime = Date.now();
+  try {
+    let finalPath = params.path;
+    if (params.pathParams) {
+      for (const [key, value] of Object.entries(params.pathParams)) {
+        finalPath = finalPath.replace(`{${key}}`, value);
+      }
+    }
+    const data = await $api.rest(finalPath, {
+      method: params.method,
+      params: params.queryParams,
+      body: params.body
+    });
+    response.value = {
+      success: true,
+      data,
+      time: Date.now() - startTime,
+      type: "rest",
+      info: `${params.method} ${finalPath}`
+    };
+  } catch (e) {
+    response.value = {
+      success: false,
+      data: e instanceof Error ? e.message : "Unknown error",
+      time: Date.now() - startTime,
+      type: "rest",
+      info: `${params.method} ${params.path}`
+    };
+  }
+}
+async function executeRpc(params) {
+  const startTime = Date.now();
+  try {
+    const data = await $api.rpc(params.service, params.method, params.body);
+    response.value = {
+      success: true,
+      data,
+      time: Date.now() - startTime,
+      type: "rpc",
+      info: `${params.service}.${params.method}`
+    };
+  } catch (e) {
+    response.value = {
+      success: false,
+      data: e instanceof Error ? e.message : "Unknown error",
+      time: Date.now() - startTime,
+      type: "rpc",
+      info: `${params.service}.${params.method}`
+    };
+  }
+}
+</script>
+
+<style scoped>
+.api-explorer{font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif;margin:0 auto;max-width:1200px;padding:2rem}.explorer-header{margin-bottom:2rem}.explorer-header h1{color:#1a1a1a;font-size:1.75rem;margin:0 0 .5rem}.explorer-header .description{color:#666;margin:0}.error,.loading{border-radius:8px;padding:2rem;text-align:center}.loading{background:#f5f5f5;color:#666}.error{background:#fff5f5;border:1px solid #dc3545;color:#dc3545}.api-section{margin:2rem 0}.section-title{align-items:center;color:#333;display:flex;font-size:1.25rem;gap:.75rem;margin:0 0 1rem}.section-title .version{color:#666;font-size:.875rem;font-weight:400}.badge{border-radius:4px;display:inline-block;font-size:.75rem;font-weight:600;padding:.25rem .5rem;text-transform:uppercase}.badge.rest{background:#61affe;color:#fff}.badge.rpc{background:#7c3aed;color:#fff}.service-group{margin:1.5rem 0}.service-name{border-bottom:2px solid #e0e0e0;color:#444;font-size:1.1rem;margin:0 0 1rem;padding-bottom:.5rem}.endpoints{display:flex;flex-direction:column;gap:.75rem}
+</style>