vite-plugin-openapi-codegen 0.0.3 → 1.0.1

package/README.md

@@ -2,10 +2,9 @@
 
 Generate typed API clients and path builders from an OpenAPI document during Vite builds.
 
-The plugin reads your OpenAPI spec, runs `openapi-typescript`, and emits four files into your target directory:
+The plugin reads your OpenAPI spec, runs `openapi-typescript`, and emits three files into your target directory:
 
 - `api-types.d.ts` for raw OpenAPI-derived types
-- `types.ts` for schema aliases
 - `api.ts` for path builder functions
 - `client.ts` for typed request helpers
 
@@ -42,7 +41,39 @@ When you run `vp dev` or `vp build`, the plugin generates:
 ```text
 src/generated/
   api-types.d.ts
-  types.ts
+  api.ts
+  client.ts
+```
+
+## Real Example Project
+
+This repository includes a real minimal Vite project under `example/` that demonstrates
+automatic generation from `vite.config.ts`.
+
+Key files:
+
+- `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
+
+Run the example build:
+
+```bash
+vp build example --config ./example/vite.config.ts
+```
+
+Run the example dev server:
+
+```bash
+vp example --config ./example/vite.config.ts
+```
+
+After either command, generated files are written to:
+
+```text
+example/src/generated/
+  api-types.d.ts
   api.ts
   client.ts
 ```
@@ -105,7 +136,9 @@ export default defineConfig({
 Given a spec path like `/api/users/{user_id}`, the plugin generates a path builder:
 
 ```ts
-export function getUser(params: UserPath): string {
+import type { components } from "./api-types";
+
+export function getUser(params: components["schemas"]["UserPath"]): string {
   return `users/${params.user_id}`;
 }
 ```
@@ -113,9 +146,11 @@ export function getUser(params: UserPath): string {
 And a typed client helper:
 
 ```ts
+import type { components } from "./api-types";
+
 export interface GetUserOptions {
   query?: never;
-  path: UserPath;
+  path: components["schemas"]["UserPath"];
   body?: never;
   signal?: AbortSignal;
 }
@@ -123,8 +158,8 @@ export interface GetUserOptions {
 export function getUser(
   options: GetUserOptions,
   requestOptions: RuntimeRequestOptions = {},
-): Promise<UserResponse> {
-  return requestJson<UserResponse>(buildGetUserPath(options.path), {
+): Promise<components["schemas"]["UserResponse"]> {
+  return requestJson<components["schemas"]["UserResponse"]>(buildGetUserPath(options.path), {
     ...requestOptions,
     method: "GET",
     signal: options.signal,
@@ -155,7 +190,6 @@ interface Options {
     requestOptionsType?: string;
     omitKeys?: string[];
   };
-  legacyAliases?: Record<string, string>;
 }
 ```
 
@@ -179,10 +213,6 @@ Controls whether the `pathPrefix` is removed from generated path builders. The d
 
 Overrides the runtime import path and symbol names used by generated clients.
 
-### `legacyAliases`
-
-Adds extra type aliases to `types.ts` so you can preserve older type names during migrations.
-
 ## Programmatic Usage
 
 If you want to generate artifacts outside the Vite lifecycle, use `renderGeneratedArtifacts`:
@@ -200,7 +230,6 @@ const files = renderGeneratedArtifacts(spec, {
 
 console.log(files.api);
 console.log(files.client);
-console.log(files.types);
 ```
 
 ## Development
@@ -211,3 +240,9 @@ vp test
 vp check
 vp pack
 ```
+
+To validate the real example project as part of local development:
+
+```bash
+vp build example --config ./example/vite.config.ts
+```

package/dist/index.d.mts

@@ -75,15 +75,12 @@ interface Options {
   stripPrefix?: boolean;
   /** HTTP client configuration */
   httpClient?: HttpClientConfig;
-  /** Legacy type aliases for types.ts: { OldName: 'NewName' } */
-  legacyAliases?: Record<string, string>;
 }
 interface GeneratedArtifacts {
   api: string;
   client: string;
-  types: string;
 }
-declare function renderGeneratedArtifacts(spec: OpenAPISpec, options: Pick<Options, "httpClient" | "legacyAliases" | "pathPrefix" | "stripPrefix">, preCollectedOperations?: OperationEntry[]): GeneratedArtifacts;
+declare function renderGeneratedArtifacts(spec: OpenAPISpec, options: Pick<Options, "httpClient" | "pathPrefix" | "stripPrefix">, preCollectedOperations?: OperationEntry[]): GeneratedArtifacts;
 declare function openapiCodegen(options: Options): Plugin;
 //#endregion
 export { type HttpClientConfig, type OpenAPISpec, type OperationEntry, type Options, openapiCodegen, renderGeneratedArtifacts };

package/dist/index.mjs

@@ -1,45 +1,33 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import * as ts from "typescript";
 //#region src/ast.ts
 const AST_PRINTER = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
-function renderTypesSource(schemaNames, legacyAliases, generatedHeader) {
-	const statements = [createTypeOnlyImport(["components"], "./api-types")];
-	for (const name of schemaNames) statements.push(ts.factory.createTypeAliasDeclaration([createExportModifier()], ts.factory.createIdentifier(name), void 0, createIndexedAccessTypeNode("components", ["schemas", name])));
-	if (legacyAliases && Object.keys(legacyAliases).length > 0) Object.entries(legacyAliases).forEach(([alias, target], index) => {
-		const statement = ts.factory.createTypeAliasDeclaration([createExportModifier()], ts.factory.createIdentifier(alias), void 0, createTypeNodeFromText(target));
-		statements.push(index === 0 ? createGeneratedBannerComment(statement, "Legacy aliases") : statement);
-	});
-	return printGeneratedFile(statements, generatedHeader);
-}
 function renderApiSource(entries, generatedHeader) {
 	const statements = [];
 	const seenGroups = /* @__PURE__ */ new Set();
-	let needsOperationsImport = false;
-	const typeAliasImports = /* @__PURE__ */ new Set();
 	for (const entry of entries) {
 		const parameters = entry.pathTypeExpr == null ? [] : [ts.factory.createParameterDeclaration(void 0, void 0, ts.factory.createIdentifier("params"), void 0, createTypeNodeFromText(entry.pathTypeExpr))];
-		if (entry.pathTypeExpr) {
-			if (entry.pathTypeExpr.includes("operations[")) needsOperationsImport = true;
-			else if (/^[A-Z]\w*$/.test(entry.pathTypeExpr)) typeAliasImports.add(entry.pathTypeExpr);
-		}
 		const declaration = ts.factory.createFunctionDeclaration([createExportModifier()], void 0, ts.factory.createIdentifier(entry.funcName), void 0, parameters, ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword), ts.factory.createBlock([ts.factory.createReturnStatement(entry.pathTypeExpr == null ? ts.factory.createStringLiteral(entry.strippedPath) : createPathExpression(entry.strippedPath))], true));
 		statements.push(seenGroups.has(entry.group) ? declaration : createGeneratedBannerComment(declaration, capitalize$1(entry.group)));
 		seenGroups.add(entry.group);
 	}
 	const sourceStatements = [];
-	if (needsOperationsImport) sourceStatements.push(createTypeOnlyImport(["operations"], "./api-types"));
-	if (typeAliasImports.size > 0) sourceStatements.push(createTypeOnlyImport([...typeAliasImports].sort(), "./types"));
+	const apiTypeImports = collectApiTypeImports(entries.map((entry) => entry.pathTypeExpr));
+	if (apiTypeImports.length > 0) sourceStatements.push(createTypeOnlyImport(apiTypeImports, "./api-types"));
 	sourceStatements.push(...statements);
 	return printGeneratedFile(sourceStatements, generatedHeader);
 }
 function renderClientSource(model, generatedHeader, httpClient) {
-	const statements = [
-		createTypeOnlyImport([httpClient.requestOptionsType], httpClient.module),
-		createValueImport([{ name: httpClient.jsonFunction }, { name: httpClient.voidFunction }], httpClient.module),
-		createTypeOnlyImport(["operations"], "./api-types")
-	];
-	if (model.typeImports.length > 0) statements.push(createTypeOnlyImport(model.typeImports, "./types"));
+	const statements = [createTypeOnlyImport([httpClient.requestOptionsType], httpClient.module), createValueImport([{ name: httpClient.jsonFunction }, { name: httpClient.voidFunction }], httpClient.module)];
+	const apiTypeImports = collectApiTypeImports(model.operations.flatMap((operation) => [
+		operation.bodyChannel.typeExpr,
+		operation.pathChannel.typeExpr,
+		operation.queryChannel.typeExpr,
+		operation.responseTypeExpr,
+		operation.returnTypeExpr
+	]));
+	if (apiTypeImports.length > 0) statements.push(createTypeOnlyImport(apiTypeImports, "./api-types"));
 	statements.push(createValueImport(model.operations.map((operation) => ({
 		alias: operation.builderAlias,
 		name: operation.funcName
@@ -80,13 +68,14 @@ function createExportModifier() {
 function createGeneratedBannerComment(node, text) {
 	return ts.addSyntheticLeadingComment(node, ts.SyntaxKind.SingleLineCommentTrivia, ` ${text}`, true);
 }
-function createStringLiteralType(value) {
-	return ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral(value));
-}
-function createIndexedAccessTypeNode(rootName, indices) {
-	let current = ts.factory.createTypeReferenceNode(rootName);
-	for (const index of indices) current = ts.factory.createIndexedAccessTypeNode(current, createStringLiteralType(index));
-	return current;
+function collectApiTypeImports(typeExprs) {
+	const names = /* @__PURE__ */ new Set();
+	for (const typeExpr of typeExprs) {
+		if (!typeExpr) continue;
+		if (typeExpr.includes("components[")) names.add("components");
+		if (typeExpr.includes("operations[")) names.add("operations");
+	}
+	return [...names].sort();
 }
 function createPathExpression(strippedPath) {
 	const matches = [...strippedPath.matchAll(/\{(\w+)\}/g)];
@@ -151,12 +140,10 @@ function buildClientRenderModelFromOperations(operations, spec, requestFunctionN
 	void: "requestVoid"
 }) {
 	const context = buildNormalizationContext(spec);
-	const typeImports = /* @__PURE__ */ new Set();
-	const normalized = operations.map((entry) => normalizeOperation(entry, context, typeImports, requestFunctionNames));
+	const normalized = operations.map((entry) => normalizeOperation(entry, context, requestFunctionNames));
 	return {
 		operations: normalized,
-		needsSearchParamsHelper: normalized.some((operation) => operation.queryChannel.present),
-		typeImports: [...typeImports].sort()
+		needsSearchParamsHelper: normalized.some((operation) => operation.queryChannel.present)
 	};
 }
 function collectOperations(spec, pathPrefix = "/api/", stripPrefix = true) {
@@ -275,24 +262,21 @@ function getTemplateParameterNames(apiPath) {
 	const matches = apiPath.match(/\{(\w+)\}/g) ?? [];
 	return new Set(matches.map((match) => match.slice(1, -1)));
 }
-function resolveParameterTypeExpression(entry, context, location, typeImports) {
+function resolveParameterTypeExpression(entry, context, location) {
 	const effectiveParameters = getEffectiveParametersByLocation(entry, location);
 	if (effectiveParameters.length === 0) return "never";
-	const alias = resolveAlias(context, effectiveParameters.map((parameter) => parameter.name), entry.operation.tags?.[0]);
-	if (alias) {
-		typeImports.add(alias);
-		return alias;
-	}
+	const schemaTypeExpr = resolveAlias(context, effectiveParameters.map((parameter) => parameter.name), entry.operation.tags?.[0]);
+	if (schemaTypeExpr) return schemaTypeExpr;
 	if (hasSameParameterNames(getParametersByLocation(entry.operation, location), effectiveParameters)) return `operations['${entry.operationId}']['parameters']['${location}']`;
 	return renderInlineParameterObject(effectiveParameters);
 }
-function normalizeOperation(entry, context, typeImports, requestFunctionNames) {
+function normalizeOperation(entry, context, requestFunctionNames) {
 	const successResponse = getSuccessResponseInfo(entry.operation);
 	const builderAlias = getBuilderAlias(entry.funcName);
-	const pathChannel = normalizeParameterChannel(entry, context, "path", typeImports);
-	const queryChannel = normalizeParameterChannel(entry, context, "query", typeImports);
-	const bodyChannel = normalizeBodyChannel(entry, context, typeImports);
-	const responseTypeExpr = resolveResponseTypeExpression(entry, context, typeImports, successResponse);
+	const pathChannel = normalizeParameterChannel(entry, context, "path");
+	const queryChannel = normalizeParameterChannel(entry, context, "query");
+	const bodyChannel = normalizeBodyChannel(entry, context);
+	const responseTypeExpr = resolveResponseTypeExpression(entry, context, successResponse);
 	return {
 		bodyChannel,
 		builderAlias,
@@ -306,7 +290,7 @@ function normalizeOperation(entry, context, typeImports, requestFunctionNames) {
 		returnTypeExpr: responseTypeExpr ? `Promise<${responseTypeExpr}>` : "Promise<void>"
 	};
 }
-function normalizeParameterChannel(entry, context, location, typeImports) {
+function normalizeParameterChannel(entry, context, location) {
 	const parameters = getEffectiveParametersByLocation(entry, location);
 	if (parameters.length === 0) return {
 		present: false,
@@ -316,11 +300,11 @@ function normalizeParameterChannel(entry, context, location, typeImports) {
 	return {
 		present: true,
 		required: hasRequiredChannel(parameters),
-		typeExpr: resolveParameterTypeExpression(entry, context, location, typeImports)
+		typeExpr: resolveParameterTypeExpression(entry, context, location)
 	};
 }
-function normalizeBodyChannel(entry, context, typeImports) {
-	const typeExpr = resolveRequestBodyTypeExpression(entry, context, typeImports);
+function normalizeBodyChannel(entry, context) {
+	const typeExpr = resolveRequestBodyTypeExpression(entry, context);
 	if (!typeExpr) return {
 		present: false,
 		required: false,
@@ -332,18 +316,18 @@ function normalizeBodyChannel(entry, context, typeImports) {
 		typeExpr
 	};
 }
-function resolveRequestBodyTypeExpression(entry, context, typeImports) {
+function resolveRequestBodyTypeExpression(entry, context) {
 	const jsonBody = getJsonRequestBody(entry.operation);
 	if (!jsonBody) return null;
-	const alias = resolveSchemaAlias(context, jsonBody.schema, typeImports);
-	if (alias) return alias;
+	const schemaTypeExpr = resolveSchemaTypeExpression(context, jsonBody.schema);
+	if (schemaTypeExpr) return schemaTypeExpr;
 	return `operations['${entry.operationId}']['requestBody']['content']['application/json']`;
 }
-function resolveResponseTypeExpression(entry, context, typeImports, successResponse) {
+function resolveResponseTypeExpression(entry, context, successResponse) {
 	if (!successResponse.hasJsonBody) return null;
 	const jsonContent = (entry.operation.responses?.[successResponse.statusKey])?.content?.["application/json"];
-	const alias = resolveSchemaAlias(context, jsonContent?.schema, typeImports);
-	if (alias) return alias;
+	const schemaTypeExpr = resolveSchemaTypeExpression(context, jsonContent?.schema);
+	if (schemaTypeExpr) return schemaTypeExpr;
 	return `operations['${entry.operationId}']['responses'][${formatStatusKey(successResponse.statusKey)}]['content']['application/json']`;
 }
 function hasSameParameterNames(left, right) {
@@ -356,22 +340,24 @@ function resolveAlias(context, parameterNames, tag) {
 	const key = [...parameterNames].sort().join(",");
 	const candidates = context.schemaAliasIndex.get(key);
 	if (!candidates || candidates.length === 0) return;
-	if (candidates.length === 1) return candidates[0];
+	if (candidates.length === 1) return createSchemaTypeExpression(candidates[0]);
 	if (tag) {
 		const singularTag = tag.replace(/s$/, "");
 		const prefix = `${singularTag[0]?.toUpperCase() ?? ""}${singularTag.slice(1)}`;
 		const match = candidates.find((candidate) => candidate.startsWith(prefix));
-		if (match) return match;
+		if (match) return createSchemaTypeExpression(match);
 	}
-	return candidates[0];
+	return createSchemaTypeExpression(candidates[0]);
 }
-function resolveSchemaAlias(context, schema, typeImports) {
+function resolveSchemaTypeExpression(context, schema) {
 	const ref = readSchemaRef(schema);
 	if (!ref) return;
 	const schemaName = ref.split("/").pop();
 	if (!schemaName || !context.schemaNames.has(schemaName)) return;
-	typeImports.add(schemaName);
-	return schemaName;
+	return createSchemaTypeExpression(schemaName);
+}
+function createSchemaTypeExpression(schemaName) {
+	return `components['schemas']['${schemaName}']`;
 }
 function readSchemaRef(schema) {
 	if (!schema || typeof schema !== "object") return;
@@ -426,11 +412,6 @@ async function generateApiTypes(inputPath, outputDir) {
 	const contents = astToString(await openapiTS(new URL(`file://${inputPath}`)));
 	writeFileSync(resolve(outputDir, "api-types.d.ts"), `${GENERATED_HEADER.join("\n")}\n\n${contents}`);
 }
-function renderTypesBarrel(spec, legacyAliases) {
-	const schemaNames = Object.keys(spec.components?.schemas ?? {}).sort();
-	if (schemaNames.length === 0) throw new Error("No schemas found in openapi.json");
-	return renderTypesSource(schemaNames, legacyAliases, GENERATED_HEADER);
-}
 function createApiEntries(normalizedOps) {
 	return normalizedOps.map((op) => ({
 		funcName: op.entry.funcName,
@@ -455,8 +436,7 @@ function createClientRenderModel(model) {
 			requestFunction: operation.requestFunction,
 			responseTypeExpr: operation.responseTypeExpr,
 			returnTypeExpr: operation.returnTypeExpr
-		})),
-		typeImports: model.typeImports
+		}))
 	};
 }
 function renderGeneratedArtifacts(spec, options, preCollectedOperations) {
@@ -470,19 +450,18 @@ function renderGeneratedArtifacts(spec, options, preCollectedOperations) {
 	if (clientModel.operations.length === 0) throw new Error(`No paths matching prefix "${pathPrefix}" found in openapi.json`);
 	return {
 		api: renderApiSource(createApiEntries(clientModel.operations), GENERATED_HEADER),
-		client: renderClientSource(createClientRenderModel(clientModel), GENERATED_HEADER, httpClient),
-		types: renderTypesBarrel(spec, options.legacyAliases)
+		client: renderClientSource(createClientRenderModel(clientModel), GENERATED_HEADER, httpClient)
 	};
 }
 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 operations = collectOperations(spec, options.pathPrefix ?? "/api/", options.stripPrefix ?? true);
 	const artifacts = renderGeneratedArtifacts(spec, options, operations);
 	warnOnParameterLocationMismatch(operations);
 	await generateApiTypes(inputPath, outputDir);
-	writeFileSync(resolve(outputDir, "types.ts"), artifacts.types);
 	writeFileSync(resolve(outputDir, "api.ts"), artifacts.api);
 	writeFileSync(resolve(outputDir, "client.ts"), artifacts.client);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-openapi-codegen",
-  "version": "0.0.3",
+  "version": "1.0.1",
   "description": "Vite plugin that generates typed API clients and route builders from OpenAPI specs",
   "keywords": [
     "api-client",