@websublime/vite-plugin-open-api-server 0.24.0-next.4 → 0.24.0-next.5

package/dist/index.d.ts

@@ -243,13 +243,44 @@ declare function resolveOptions(options: OpenApiServerOptions): ResolvedOptions;
 /**
  * Vite Plugin Implementation
  *
- * What: Main Vite plugin for OpenAPI mock server
- * How: Uses configureServer hook to start mock server and configure proxy
- * Why: Integrates OpenAPI mock server seamlessly into Vite dev workflow
+ * What: Main Vite plugin for OpenAPI mock server (multi-spec)
+ * How: Uses orchestrator to create N spec instances, configures multi-proxy
+ * Why: Integrates multiple OpenAPI mock servers seamlessly into Vite dev workflow
  *
  * @module plugin
  */
 
+/**
+ * Create the OpenAPI Server Vite plugin
+ *
+ * This plugin starts mock servers based on OpenAPI specifications
+ * and configures Vite to proxy API requests to them. Supports
+ * multiple specs via the orchestrator pattern.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import vue from '@vitejs/plugin-vue';
+ * import { openApiServer } from '@websublime/vite-plugin-open-api-server';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     vue(),
+ *     openApiServer({
+ *       specs: [
+ *         { spec: './openapi/petstore.yaml', proxyPath: '/api/pets' },
+ *         { spec: './openapi/inventory.yaml', proxyPath: '/api/inventory' },
+ *       ],
+ *       port: 4000,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @param options - Plugin configuration options
+ * @returns Vite plugin
+ */
 declare function openApiServer(options: OpenApiServerOptions): Plugin;
 
 /**
@@ -467,7 +498,13 @@ interface SpecInstance {
  * individual spec instances, aggregated metadata, and lifecycle methods.
  */
 interface OrchestratorResult {
-    /** Main Hono app with all specs mounted via X-Spec-Id dispatch */
+    /**
+     * Main Hono app with all specs mounted via X-Spec-Id dispatch.
+     *
+     * **Note**: Consumers using this property directly must have `hono`
+     * as a dependency. The `start()`/`stop()` lifecycle methods do not
+     * require direct interaction with this Hono instance.
+     */
     app: Hono;
     /** All spec instances (in config order) */
     instances: SpecInstance[];
@@ -491,9 +528,10 @@ interface OrchestratorResult {
  * 3. **Phase 3 — Build main app**: Create a single Hono app with CORS,
  *    DevTools, Internal API, and X-Spec-Id dispatch middleware.
  *
- * **Note**: This function mutates `options.specs[i]` to write back resolved
- * values (id, proxyPath, proxyPathSource, handlersDir, seedsDir) so that
- * downstream consumers (banner, file watcher, plugin.ts) see the final values.
+ * **Note**: This function populates the resolved values (id, proxyPath,
+ * proxyPathSource, handlersDir, seedsDir) on each `options.specs[i]` object.
+ * Since `instances[i].config` is the same object reference, consumers should
+ * access resolved values through `instances[i].config` (the authoritative view).
  *
  * @param options - Resolved plugin options (from `resolveOptions()`)
  * @param vite - Vite dev server instance (for ssrLoadModule)
@@ -513,6 +551,17 @@ declare function createOrchestrator(options: ResolvedOptions, vite: ViteDevServe
  * @module multi-proxy
  */
 
+/**
+ * Shared service proxy path prefixes.
+ *
+ * These constants are the single source of truth for the reserved proxy paths
+ * used by the DevTools iframe, internal API, and WebSocket connections.
+ * Both `configureMultiProxy()` and the virtual DevTools tab module in
+ * `plugin.ts` reference these to prevent divergence.
+ */
+declare const DEVTOOLS_PROXY_PATH = "/_devtools";
+declare const API_PROXY_PATH = "/_api";
+declare const WS_PROXY_PATH = "/_ws";
 /**
  * Configure Vite proxy for multiple spec instances and shared services.
  *
@@ -766,7 +815,7 @@ declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, dela
 interface RegisterDevToolsOptions {
     /**
      * The port where the OpenAPI server is running
-     * @default 3000
+     * @default 4000
      */
     port?: number;
     /**
@@ -808,7 +857,7 @@ interface RegisterDevToolsOptions {
  *
  * // Register OpenAPI Server DevTools
  * if (import.meta.env.DEV) {
- *   await registerDevTools(app, { port: 3000 });
+ *   await registerDevTools(app);
  * }
  *
  * app.mount('#app');
@@ -824,11 +873,11 @@ declare function registerDevTools(app: App, options?: RegisterDevToolsOptions):
  * When running in a browser, protocol and host are automatically derived from
  * window.location if not explicitly provided.
  *
- * @param port - Server port (default: 3000)
+ * @param port - Server port (default: 4000, matching OpenApiServerOptions.port)
  * @param host - Server host (default: 'localhost' or window.location.hostname)
  * @param protocol - Protocol to use (default: 'http' or window.location.protocol)
  * @returns DevTools SPA URL
  */
 declare function getDevToolsUrl(port?: number, host?: string, protocol?: 'http' | 'https'): string;
 
-export { type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, configureMultiProxy, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };
+export { API_PROXY_PATH, DEVTOOLS_PROXY_PATH, type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, WS_PROXY_PATH, configureMultiProxy, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };