vite-plugin-openapi-codegen 1.0.1 → 1.1.0

package/README.md

@@ -1,14 +1,14 @@
 # vite-plugin-openapi-codegen
 
-Generate typed API clients and path builders from an OpenAPI document during Vite builds.
+Generate typed API clients and path builders from a local or online OpenAPI document during Vite dev runs.
 
-The plugin reads your OpenAPI spec, runs `openapi-typescript`, and emits three files into your target directory:
+The plugin reads your OpenAPI JSON or YAML spec, runs `openapi-typescript`, and emits three files into your target directory:
 
 - `api-types.d.ts` for raw OpenAPI-derived types
 - `api.ts` for path builder functions
 - `client.ts` for typed request helpers
 
-It also watches the input spec in dev mode and regenerates the files when the spec changes.
+It also watches local input specs in dev mode and regenerates the files when the spec changes. In dev mode, generation runs in the background so Vite can finish starting even if the remote spec is temporarily unavailable. Online `http://` and `https://` inputs are fetched once when Vite starts. Build mode skips the plugin entirely.
 
 ## Installation
 
@@ -36,7 +36,23 @@ export default defineConfig({
 });
 ```
 
-When you run `vp dev` or `vp build`, the plugin generates:
+Online YAML inputs use the same option:
+
+```ts
+import { defineConfig } from "vite-plus";
+import { openapiCodegen } from "vite-plugin-openapi-codegen";
+
+export default defineConfig({
+  plugins: [
+    openapiCodegen({
+      input: "https://example.com/openapi.yaml",
+      output: "src/generated",
+    }),
+  ],
+});
+```
+
+When you run `vp dev`, the plugin generates:
 
 ```text
 src/generated/
@@ -45,39 +61,41 @@ src/generated/
   client.ts
 ```
 
-## Real Example Project
+## Example Projects
+
+This repository includes two minimal Vite demos under `example/`:
 
-This repository includes a real minimal Vite project under `example/` that demonstrates
-automatic generation from `vite.config.ts`.
+- `example/local` demonstrates generation from the shared local file `example/openapi.json`
+- `example/online` demonstrates generation from `http://localhost:8080/openapi.yaml`
+- Both demos reuse the shared runtime helper in `example/src/http.ts`
 
-Key files:
+Run the local demo in dev mode:
 
-- `example/vite.config.ts` wires the plugin into Vite
-- `example/openapi.json` is the input spec
-- `example/src/http.ts` provides the runtime symbols used by generated clients
-- `example/src/generated/*` is generated during build/dev and is gitignored
+```bash
+vp dev example/local --config ./example/local/vite.config.ts
+```
 
-Run the example build:
+Run the online demo in dev mode:
 
 ```bash
-vp build example --config ./example/vite.config.ts
+vp dev example/online --config ./example/online/vite.config.ts
 ```
 
-Run the example dev server:
+Start both demos together with the shared mock OpenAPI server:
 
 ```bash
-vp example --config ./example/vite.config.ts
+vp run dev:examples
 ```
 
-After either command, generated files are written to:
+Build either demo shell without running code generation:
 
-```text
-example/src/generated/
-  api-types.d.ts
-  api.ts
-  client.ts
+```bash
+vp build example/local --config ./example/local/vite.config.ts
+vp build example/online --config ./example/online/vite.config.ts
 ```
 
+When you run the dev server, generated files are written to `example/<demo>/src/generated/` and are ignored by git.
+
 ## Runtime Contract
 
 By default, generated clients import the following symbols from `#/integrations/http`:
@@ -195,7 +213,9 @@ interface Options {
 
 ### `input`
 
-Path to the OpenAPI JSON file, relative to the Vite project root.
+Path or URL to the OpenAPI JSON/YAML document. Local paths are resolved relative to the Vite project root and watched in dev mode. Online `http://` and `https://` URLs are fetched once at startup and are not watched.
+
+In dev mode, generation errors are logged and do not stop Vite from starting. In build mode, the plugin is skipped entirely.
 
 ### `output`
 
@@ -244,5 +264,6 @@ vp pack
 To validate the real example project as part of local development:
 
 ```bash
-vp build example --config ./example/vite.config.ts
+vp build example/local --config ./example/local/vite.config.ts
+vp build example/online --config ./example/online/vite.config.ts
 ```

package/dist/index.d.mts

@@ -65,7 +65,7 @@ interface HttpClientConfig {
   omitKeys?: string[];
 }
 interface Options {
-  /** Path to openapi.json (relative to project root) */
+  /** Path or HTTP(S) URL to an OpenAPI JSON/YAML document */
   input: string;
   /** Output directory for generated files (relative to project root) */
   output: string;

package/dist/index.mjs

@@ -1,5 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse } from "yaml";
 import * as ts from "typescript";
 //#region src/ast.ts
 const AST_PRINTER = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
@@ -407,9 +409,9 @@ function resolveHttpClientConfig(config) {
 	};
 }
 const GENERATED_HEADER = ["// This file is auto-generated by vite-plugin-openapi-codegen.", "// Do not edit manually. Changes will be overwritten on next build."];
-async function generateApiTypes(inputPath, outputDir) {
+async function generateApiTypes(source, outputDir) {
 	const { default: openapiTS, astToString } = await import("openapi-typescript");
-	const contents = astToString(await openapiTS(new URL(`file://${inputPath}`)));
+	const contents = astToString(await openapiTS(source));
 	writeFileSync(resolve(outputDir, "api-types.d.ts"), `${GENERATED_HEADER.join("\n")}\n\n${contents}`);
 }
 function createApiEntries(normalizedOps) {
@@ -453,41 +455,88 @@ function renderGeneratedArtifacts(spec, options, preCollectedOperations) {
 		client: renderClientSource(createClientRenderModel(clientModel), GENERATED_HEADER, httpClient)
 	};
 }
+async function loadOpenAPIInput(root, input) {
+	if (isHttpUrl(input)) {
+		const sourceText = await fetchRemoteOpenAPIInput(input);
+		return {
+			apiTypesSource: sourceText,
+			spec: parseOpenAPISpec(sourceText, input)
+		};
+	}
+	const inputPath = resolve(root, input);
+	const sourceText = readFileSync(inputPath, "utf-8");
+	return {
+		apiTypesSource: pathToFileURL(inputPath),
+		spec: parseOpenAPISpec(sourceText, inputPath)
+	};
+}
+function isHttpUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+async function fetchRemoteOpenAPIInput(input) {
+	const response = await fetch(input);
+	if (!response.ok) throw new Error(`[openapi-codegen] Failed to fetch OpenAPI document from ${input}: ${response.status} ${response.statusText}`);
+	return response.text();
+}
+function parseOpenAPISpec(sourceText, inputLabel) {
+	const parsed = parse(sourceText);
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`[openapi-codegen] Expected OpenAPI document object from ${inputLabel}`);
+	return parsed;
+}
 async function generate(root, options) {
-	const inputPath = resolve(root, options.input);
 	const outputDir = resolve(root, options.output);
 	mkdirSync(outputDir, { recursive: true });
-	const spec = JSON.parse(readFileSync(inputPath, "utf-8"));
+	const { apiTypesSource, spec } = await loadOpenAPIInput(root, options.input);
 	const operations = collectOperations(spec, options.pathPrefix ?? "/api/", options.stripPrefix ?? true);
 	const artifacts = renderGeneratedArtifacts(spec, options, operations);
 	warnOnParameterLocationMismatch(operations);
-	await generateApiTypes(inputPath, outputDir);
+	await generateApiTypes(apiTypesSource, outputDir);
 	writeFileSync(resolve(outputDir, "api.ts"), artifacts.api);
 	writeFileSync(resolve(outputDir, "client.ts"), artifacts.client);
 }
 function openapiCodegen(options) {
 	let root = process.cwd();
+	let command = "build";
 	return {
 		name: "openapi-codegen",
 		enforce: "pre",
 		configResolved(config) {
 			root = config.root;
+			command = config.command;
 		},
 		async buildStart() {
-			await generate(root, options);
+			if (command === "serve") {
+				runDevelopmentGeneration(root, options);
+				return;
+			}
 		},
 		configureServer(server) {
+			if (isHttpUrl(options.input)) return;
 			const inputPath = resolve(root, options.input);
 			server.watcher.add(inputPath);
 			server.watcher.on("change", async (path) => {
 				if (path === inputPath) {
 					console.log("[openapi-codegen] openapi.json changed, regenerating...");
-					await generate(root, options);
-					console.log("[openapi-codegen] regeneration complete.");
+					runDevelopmentGeneration(root, options, { onSuccess: () => {
+						console.log("[openapi-codegen] regeneration complete.");
+					} });
 				}
 			});
 		}
 	};
 }
+async function runDevelopmentGeneration(root, options, handlers) {
+	try {
+		await generate(root, options);
+		handlers?.onSuccess?.();
+	} catch (error) {
+		console.error("[openapi-codegen] generation failed during dev mode.", error);
+	}
+}
 //#endregion
 export { openapiCodegen, renderGeneratedArtifacts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-openapi-codegen",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Vite plugin that generates typed API clients and route builders from OpenAPI specs",
   "keywords": [
     "api-client",
@@ -38,6 +38,7 @@
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
+    "dev:examples": "node scripts/dev-examples.mjs",
     "test": "vp test",
     "check": "vp check",
     "release": "bumpp --no-verify",
@@ -45,7 +46,8 @@
   },
   "dependencies": {
     "openapi-typescript": "^7.13.0",
-    "typescript": ">=5.0.0"
+    "typescript": ">=5.0.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",