vite-plugin-openapi-codegen 0.0.3

package/README.md

@@ -0,0 +1,213 @@
+# vite-plugin-openapi-codegen
+
+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:
+
+- `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
+
+It also watches the input spec in dev mode and regenerates the files when the spec changes.
+
+## Installation
+
+This package is built for `vite-plus`.
+
+```bash
+vp add -D vite-plugin-openapi-codegen vite-plus
+```
+
+## Usage
+
+Add the plugin to your Vite config:
+
+```ts
+import { defineConfig } from "vite-plus";
+import { openapiCodegen } from "vite-plugin-openapi-codegen";
+
+export default defineConfig({
+  plugins: [
+    openapiCodegen({
+      input: "openapi.json",
+      output: "src/generated",
+    }),
+  ],
+});
+```
+
+When you run `vp dev` or `vp build`, the plugin generates:
+
+```text
+src/generated/
+  api-types.d.ts
+  types.ts
+  api.ts
+  client.ts
+```
+
+## Runtime Contract
+
+By default, generated clients import the following symbols from `#/integrations/http`:
+
+- `requestJson`
+- `requestVoid`
+- `ApiRequestOptions`
+
+The default runtime shape is designed for an app-level HTTP wrapper like this:
+
+```ts
+export interface ApiRequestOptions {
+  headers?: Record<string, string>;
+  json?: unknown;
+  method: string;
+  searchParams?: URLSearchParams;
+  signal?: AbortSignal;
+}
+
+export async function requestJson<T>(path: string, options: ApiRequestOptions): Promise<T> {
+  // Your app-specific HTTP implementation
+  throw new Error("Not implemented");
+}
+
+export async function requestVoid(path: string, options: ApiRequestOptions): Promise<void> {
+  // Your app-specific HTTP implementation
+  throw new Error("Not implemented");
+}
+```
+
+If your runtime uses different symbol names or a different module path, configure `httpClient`:
+
+```ts
+import { defineConfig } from "vite-plus";
+import { openapiCodegen } from "vite-plugin-openapi-codegen";
+
+export default defineConfig({
+  plugins: [
+    openapiCodegen({
+      input: "openapi.json",
+      output: "src/generated",
+      httpClient: {
+        module: "@app/http",
+        jsonFunction: "fetchJson",
+        voidFunction: "fetchVoid",
+        requestOptionsType: "RequestOptions",
+        omitKeys: ["json", "method", "signal"],
+      },
+    }),
+  ],
+});
+```
+
+## Generated Output
+
+Given a spec path like `/api/users/{user_id}`, the plugin generates a path builder:
+
+```ts
+export function getUser(params: UserPath): string {
+  return `users/${params.user_id}`;
+}
+```
+
+And a typed client helper:
+
+```ts
+export interface GetUserOptions {
+  query?: never;
+  path: UserPath;
+  body?: never;
+  signal?: AbortSignal;
+}
+
+export function getUser(
+  options: GetUserOptions,
+  requestOptions: RuntimeRequestOptions = {},
+): Promise<UserResponse> {
+  return requestJson<UserResponse>(buildGetUserPath(options.path), {
+    ...requestOptions,
+    method: "GET",
+    signal: options.signal,
+  });
+}
+```
+
+The generated client shape depends on the OpenAPI operation:
+
+- path parameters become `options.path`
+- query parameters become `options.query`
+- JSON request bodies become `options.body`
+- JSON responses become typed `Promise<T>`
+- empty responses use the configured void request function
+
+## Options
+
+```ts
+interface Options {
+  input: string;
+  output: string;
+  pathPrefix?: string;
+  stripPrefix?: boolean;
+  httpClient?: {
+    module?: string;
+    jsonFunction?: string;
+    voidFunction?: string;
+    requestOptionsType?: string;
+    omitKeys?: string[];
+  };
+  legacyAliases?: Record<string, string>;
+}
+```
+
+### `input`
+
+Path to the OpenAPI JSON file, relative to the Vite project root.
+
+### `output`
+
+Directory where generated files are written, relative to the Vite project root.
+
+### `pathPrefix`
+
+Only paths starting with this prefix are included. The default is `"/api/"`.
+
+### `stripPrefix`
+
+Controls whether the `pathPrefix` is removed from generated path builders. The default is `true`.
+
+### `httpClient`
+
+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`:
+
+```ts
+import { readFileSync } from "node:fs";
+import { renderGeneratedArtifacts } from "vite-plugin-openapi-codegen";
+
+const spec = JSON.parse(readFileSync("openapi.json", "utf-8"));
+
+const files = renderGeneratedArtifacts(spec, {
+  pathPrefix: "/api/",
+  stripPrefix: true,
+});
+
+console.log(files.api);
+console.log(files.client);
+console.log(files.types);
+```
+
+## Development
+
+```bash
+vp install
+vp test
+vp check
+vp pack
+```

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+import { Plugin } from "vite-plus";
+
+//#region src/normalization.d.ts
+declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "patch"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+type ParameterLocation = "path" | "query" | "header" | "cookie";
+interface OpenAPIParameter {
+  in: ParameterLocation;
+  name: string;
+  required?: boolean;
+  schema?: {
+    type?: string | string[];
+  };
+}
+interface OpenAPIContent {
+  schema?: unknown;
+}
+interface OpenAPIRequestBody {
+  content?: Record<string, OpenAPIContent>;
+  required?: boolean;
+}
+interface OpenAPIResponse {
+  content?: Record<string, OpenAPIContent>;
+  description?: string;
+}
+interface OpenAPIOperation {
+  operationId?: string;
+  parameters?: OpenAPIParameter[];
+  requestBody?: OpenAPIRequestBody;
+  responses?: Record<string, OpenAPIResponse>;
+  tags?: string[];
+}
+type OpenAPIPathItem = Partial<Record<HttpMethod, OpenAPIOperation>>;
+interface OpenAPISchema {
+  properties?: Record<string, unknown>;
+  type?: string;
+}
+interface OpenAPISpec {
+  paths?: Record<string, OpenAPIPathItem>;
+  components?: {
+    schemas?: Record<string, OpenAPISchema>;
+  };
+}
+interface OperationEntry {
+  apiPath: string;
+  funcName: string;
+  group: string;
+  method: HttpMethod;
+  operation: OpenAPIOperation;
+  operationId: string;
+  strippedPath: string;
+}
+//#endregion
+//#region src/plugin.d.ts
+interface HttpClientConfig {
+  /** HTTP module import path. Default: '#/integrations/http' */
+  module?: string;
+  /** Function name for JSON-returning requests. Default: 'requestJson' */
+  jsonFunction?: string;
+  /** Function name for void requests. Default: 'requestVoid' */
+  voidFunction?: string;
+  /** Type name for request options (type-only import). Default: 'ApiRequestOptions' */
+  requestOptionsType?: string;
+  /** Keys to Omit from requestOptionsType for RuntimeRequestOptions. Default: ['json','method','searchParams','signal'] */
+  omitKeys?: string[];
+}
+interface Options {
+  /** Path to openapi.json (relative to project root) */
+  input: string;
+  /** Output directory for generated files (relative to project root) */
+  output: string;
+  /** Path prefix for filtering and stripping. Default: '/api/' */
+  pathPrefix?: string;
+  /** Whether to strip pathPrefix from generated paths. Default: true */
+  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 openapiCodegen(options: Options): Plugin;
+//#endregion
+export { type HttpClientConfig, type OpenAPISpec, type OperationEntry, type Options, openapiCodegen, renderGeneratedArtifacts };

package/dist/index.mjs

@@ -0,0 +1,514 @@
+import { 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"));
+	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"));
+	statements.push(createValueImport(model.operations.map((operation) => ({
+		alias: operation.builderAlias,
+		name: operation.funcName
+	})), "./api"));
+	const runtimeTypeExpr = httpClient.omitKeys.length > 0 ? `Omit<${httpClient.requestOptionsType}, ${httpClient.omitKeys.map((k) => `'${k}'`).join(" | ")}>` : httpClient.requestOptionsType;
+	statements.push(ts.factory.createTypeAliasDeclaration(void 0, ts.factory.createIdentifier("RuntimeRequestOptions"), void 0, createTypeNodeFromText(runtimeTypeExpr)));
+	if (model.needsSearchParamsHelper) statements.push(createBuildSearchParamsFunction());
+	const seenGroups = /* @__PURE__ */ new Set();
+	for (const operation of model.operations) {
+		const optionsInterface = createClientOptionsDeclaration(operation);
+		statements.push(seenGroups.has(operation.group) ? optionsInterface : createGeneratedBannerComment(optionsInterface, capitalize$1(operation.group)));
+		statements.push(createClientFunctionDeclaration(operation));
+		seenGroups.add(operation.group);
+	}
+	return printGeneratedFile(statements, generatedHeader);
+}
+function printGeneratedFile(statements, generatedHeader) {
+	const sourceFile = ts.factory.createSourceFile(statements, ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
+	const printed = AST_PRINTER.printFile(sourceFile).trim();
+	return printed.length > 0 ? `${generatedHeader.join("\n")}\n\n${printed}\n` : `${generatedHeader.join("\n")}\n`;
+}
+function parseExpression(sourceText) {
+	const statement = ts.createSourceFile("generated-expression.ts", `const value = ${sourceText}`, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS).statements[0];
+	if (!statement || !ts.isVariableStatement(statement)) throw new Error(`Failed to parse expression: ${sourceText}`);
+	const declaration = statement.declarationList.declarations[0];
+	if (!declaration?.initializer) throw new Error(`Missing parsed initializer for: ${sourceText}`);
+	return declaration.initializer;
+}
+function createTypeOnlyImport(names, moduleSpecifier) {
+	return ts.factory.createImportDeclaration(void 0, ts.factory.createImportClause(true, void 0, ts.factory.createNamedImports(names.map((name) => ts.factory.createImportSpecifier(false, void 0, ts.factory.createIdentifier(name))))), ts.factory.createStringLiteral(moduleSpecifier));
+}
+function createValueImport(specifiers, moduleSpecifier) {
+	return ts.factory.createImportDeclaration(void 0, ts.factory.createImportClause(false, void 0, ts.factory.createNamedImports(specifiers.map((specifier) => ts.factory.createImportSpecifier(false, specifier.alias ? ts.factory.createIdentifier(specifier.name) : void 0, ts.factory.createIdentifier(specifier.alias ?? specifier.name))))), ts.factory.createStringLiteral(moduleSpecifier));
+}
+function createExportModifier() {
+	return ts.factory.createModifier(ts.SyntaxKind.ExportKeyword);
+}
+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 createPathExpression(strippedPath) {
+	const matches = [...strippedPath.matchAll(/\{(\w+)\}/g)];
+	if (matches.length === 0) return ts.factory.createStringLiteral(strippedPath);
+	const [firstMatch] = matches;
+	const spans = matches.map((match, index) => {
+		const nextMatch = matches[index + 1];
+		const literalText = strippedPath.slice(match.index + match[0].length, nextMatch?.index ?? strippedPath.length);
+		return ts.factory.createTemplateSpan(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("params"), match[1]), nextMatch ? ts.factory.createTemplateMiddle(literalText) : ts.factory.createTemplateTail(literalText));
+	});
+	return ts.factory.createTemplateExpression(ts.factory.createTemplateHead(strippedPath.slice(0, firstMatch.index)), spans);
+}
+function createTypeNodeFromText(sourceText) {
+	const stmt = ts.createSourceFile("__type__.ts", `type __T__ = ${sourceText}`, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS).statements[0];
+	if (!stmt || !ts.isTypeAliasDeclaration(stmt)) throw new Error(`Failed to parse type expression: ${sourceText}`);
+	return stmt.type;
+}
+function createClientOptionsDeclaration(operation) {
+	return ts.factory.createInterfaceDeclaration([createExportModifier()], ts.factory.createIdentifier(operation.optionTypeName), void 0, void 0, [
+		createClientChannelField("query", operation.queryChannel),
+		createClientChannelField("path", operation.pathChannel),
+		createClientChannelField("body", operation.bodyChannel),
+		ts.factory.createPropertySignature(void 0, ts.factory.createIdentifier("signal"), ts.factory.createToken(ts.SyntaxKind.QuestionToken), ts.factory.createTypeReferenceNode("AbortSignal"))
+	]);
+}
+function createClientChannelField(key, channel) {
+	return ts.factory.createPropertySignature(void 0, ts.factory.createIdentifier(key), channel.present && channel.required ? void 0 : ts.factory.createToken(ts.SyntaxKind.QuestionToken), channel.present && channel.typeExpr ? createTypeNodeFromText(channel.typeExpr) : ts.factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword));
+}
+function createClientFunctionDeclaration(operation) {
+	const requestProperties = [ts.factory.createSpreadAssignment(ts.factory.createIdentifier("requestOptions")), ts.factory.createPropertyAssignment(ts.factory.createIdentifier("method"), ts.factory.createStringLiteral(operation.methodUpper))];
+	if (operation.queryChannel.present) requestProperties.push(ts.factory.createPropertyAssignment(ts.factory.createIdentifier("searchParams"), ts.factory.createCallExpression(ts.factory.createIdentifier("buildSearchParams"), void 0, [ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("options"), "query")])));
+	if (operation.bodyChannel.present) requestProperties.push(ts.factory.createPropertyAssignment(ts.factory.createIdentifier("json"), ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("options"), "body")));
+	requestProperties.push(ts.factory.createPropertyAssignment(ts.factory.createIdentifier("signal"), ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("options"), "signal")));
+	const requestCall = ts.factory.createCallExpression(ts.factory.createIdentifier(operation.requestFunction), operation.responseTypeExpr ? [createTypeNodeFromText(operation.responseTypeExpr)] : void 0, [parseExpression(operation.pathInvocationExpr), ts.factory.createObjectLiteralExpression(requestProperties, true)]);
+	return ts.factory.createFunctionDeclaration([createExportModifier()], void 0, ts.factory.createIdentifier(operation.funcName), void 0, [ts.factory.createParameterDeclaration(void 0, void 0, ts.factory.createIdentifier("options"), void 0, ts.factory.createTypeReferenceNode(operation.optionTypeName)), ts.factory.createParameterDeclaration(void 0, void 0, ts.factory.createIdentifier("requestOptions"), void 0, ts.factory.createTypeReferenceNode("RuntimeRequestOptions"), ts.factory.createObjectLiteralExpression())], createTypeNodeFromText(operation.returnTypeExpr), ts.factory.createBlock([ts.factory.createReturnStatement(requestCall)], true));
+}
+function createBuildSearchParamsFunction() {
+	return ts.factory.createFunctionDeclaration(void 0, void 0, ts.factory.createIdentifier("buildSearchParams"), void 0, [ts.factory.createParameterDeclaration(void 0, void 0, ts.factory.createIdentifier("query"), void 0, createTypeNodeFromText("Record<string, unknown> | undefined"))], createTypeNodeFromText("URLSearchParams | undefined"), ts.factory.createBlock([
+		ts.factory.createIfStatement(ts.factory.createBinaryExpression(ts.factory.createIdentifier("query"), ts.factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken), ts.factory.createIdentifier("undefined")), ts.factory.createReturnStatement(ts.factory.createIdentifier("undefined"))),
+		ts.factory.createVariableStatement(void 0, ts.factory.createVariableDeclarationList([ts.factory.createVariableDeclaration(ts.factory.createIdentifier("entries"), void 0, void 0, parseExpression("Object.entries(query).filter(([, value]) => value != null)"))], ts.NodeFlags.Const)),
+		ts.factory.createIfStatement(ts.factory.createBinaryExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("entries"), "length"), ts.factory.createToken(ts.SyntaxKind.EqualsEqualsEqualsToken), ts.factory.createNumericLiteral("0")), ts.factory.createReturnStatement(ts.factory.createIdentifier("undefined"))),
+		ts.factory.createVariableStatement(void 0, ts.factory.createVariableDeclarationList([ts.factory.createVariableDeclaration(ts.factory.createIdentifier("searchParams"), void 0, void 0, ts.factory.createNewExpression(ts.factory.createIdentifier("URLSearchParams"), void 0, []))], ts.NodeFlags.Const)),
+		ts.factory.createForOfStatement(void 0, ts.factory.createVariableDeclarationList([ts.factory.createVariableDeclaration(ts.factory.createArrayBindingPattern([ts.factory.createBindingElement(void 0, void 0, "key"), ts.factory.createBindingElement(void 0, void 0, "value")]))], ts.NodeFlags.Const), ts.factory.createIdentifier("entries"), ts.factory.createBlock([ts.factory.createExpressionStatement(ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier("searchParams"), "set"), void 0, [ts.factory.createIdentifier("key"), ts.factory.createCallExpression(ts.factory.createIdentifier("String"), void 0, [ts.factory.createIdentifier("value")])]))], true)),
+		ts.factory.createReturnStatement(ts.factory.createIdentifier("searchParams"))
+	], true));
+}
+function capitalize$1(value) {
+	if (value.length === 0) return value;
+	return `${value[0].toUpperCase()}${value.slice(1)}`;
+}
+//#endregion
+//#region src/normalization.ts
+const HTTP_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"patch"
+];
+function buildClientRenderModelFromOperations(operations, spec, requestFunctionNames = {
+	json: "requestJson",
+	void: "requestVoid"
+}) {
+	const context = buildNormalizationContext(spec);
+	const typeImports = /* @__PURE__ */ new Set();
+	const normalized = operations.map((entry) => normalizeOperation(entry, context, typeImports, requestFunctionNames));
+	return {
+		operations: normalized,
+		needsSearchParamsHelper: normalized.some((operation) => operation.queryChannel.present),
+		typeImports: [...typeImports].sort()
+	};
+}
+function collectOperations(spec, pathPrefix = "/api/", stripPrefix = true) {
+	const apiPaths = Object.keys(spec.paths ?? {}).filter((path) => path.startsWith(pathPrefix)).sort();
+	if (apiPaths.length === 0) throw new Error(`No paths matching prefix "${pathPrefix}" found in openapi.json`);
+	const entries = [];
+	for (const apiPath of apiPaths) {
+		const pathItem = spec.paths?.[apiPath];
+		if (!pathItem) continue;
+		for (const method of HTTP_METHODS) {
+			const operation = pathItem[method];
+			if (!operation?.operationId) continue;
+			const strippedPath = stripPrefix ? apiPath.replace(pathPrefix, "") : apiPath;
+			entries.push({
+				apiPath,
+				funcName: makeFuncName(method, apiPath, pathPrefix),
+				group: strippedPath.split("/")[0] ?? "misc",
+				method,
+				operation,
+				operationId: operation.operationId,
+				strippedPath
+			});
+		}
+	}
+	return entries;
+}
+function getEffectiveParametersByLocation(entry, location) {
+	return (entry.operation.parameters ?? []).filter((parameter) => getEffectiveParameterLocation(entry.apiPath, parameter) === location);
+}
+function warnOnParameterLocationMismatch(operations) {
+	for (const entry of operations) for (const parameter of entry.operation.parameters ?? []) {
+		const effectiveLocation = getEffectiveParameterLocation(entry.apiPath, parameter);
+		if (effectiveLocation === parameter.in) continue;
+		console.warn(`[openapi-codegen] normalized parameter "${parameter.name}" for "${entry.operationId}" from ${parameter.in} to ${effectiveLocation}.`);
+	}
+}
+function buildNormalizationContext(spec) {
+	const schemaAliasIndex = /* @__PURE__ */ new Map();
+	const schemaNames = /* @__PURE__ */ new Set();
+	for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
+		schemaNames.add(name);
+		const props = Object.keys(schema.properties ?? {}).sort().join(",");
+		if (!props) continue;
+		if (!schemaAliasIndex.has(props)) schemaAliasIndex.set(props, []);
+		schemaAliasIndex.get(props)?.push(name);
+	}
+	return {
+		schemaAliasIndex,
+		schemaNames
+	};
+}
+function getParametersByLocation(operation, location) {
+	return (operation.parameters ?? []).filter((parameter) => parameter.in === location);
+}
+function hasRequiredChannel(parameters) {
+	return parameters.some((parameter) => parameter.required);
+}
+function getJsonRequestBody(operation) {
+	const requestBody = operation.requestBody;
+	if (!requestBody) return void 0;
+	const jsonBody = requestBody.content?.["application/json"];
+	if (!jsonBody) throw new Error(`Operation "${operation.operationId ?? "unknown"}" has a requestBody but no application/json content`);
+	return jsonBody;
+}
+function getSuccessResponseInfo(operation) {
+	const successResponses = Object.entries(operation.responses ?? {}).filter(([statusKey]) => isSuccessStatus(statusKey)).sort(([left], [right]) => Number(left) - Number(right));
+	if (successResponses.length === 0) throw new Error(`Operation "${operation.operationId ?? "unknown"}" has no 2xx success response`);
+	const withJson = successResponses.find(([, response]) => response.content?.["application/json"]);
+	if (withJson) return {
+		hasJsonBody: true,
+		statusKey: withJson[0]
+	};
+	return {
+		hasJsonBody: false,
+		statusKey: successResponses[0][0]
+	};
+}
+function isSuccessStatus(statusKey) {
+	const value = Number(statusKey);
+	return Number.isInteger(value) && value >= 200 && value < 300;
+}
+function formatStatusKey(statusKey) {
+	return Number.isInteger(Number(statusKey)) ? statusKey : `'${statusKey}'`;
+}
+function getBuilderAlias(funcName) {
+	return `build${capitalize(funcName)}Path`;
+}
+function getClientOptionTypeName(funcName) {
+	return `${capitalize(funcName)}Options`;
+}
+function makeFuncName(method, apiPath, pathPrefix = "/api/") {
+	const segments = apiPath.replace(pathPrefix, "").split("/");
+	const result = [];
+	for (const segment of segments) {
+		if (segment.startsWith("{")) {
+			const resource = segment.slice(1, -1).replace(/_id$/, "");
+			if (result.length > 0) result[result.length - 1] = resource;
+			continue;
+		}
+		result.push(segment);
+	}
+	return `${method}${capitalize(result.map((segment, index) => {
+		const clean = segment.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+		return index === 0 ? clean : `${clean[0].toUpperCase()}${clean.slice(1)}`;
+	}).join(""))}`;
+}
+function capitalize(value) {
+	if (value.length === 0) return value;
+	return `${value[0].toUpperCase()}${value.slice(1)}`;
+}
+function getEffectiveParameterLocation(apiPath, parameter) {
+	if (parameter.in !== "path") return parameter.in;
+	return getTemplateParameterNames(apiPath).has(parameter.name) ? "path" : "query";
+}
+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) {
+	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;
+	}
+	if (hasSameParameterNames(getParametersByLocation(entry.operation, location), effectiveParameters)) return `operations['${entry.operationId}']['parameters']['${location}']`;
+	return renderInlineParameterObject(effectiveParameters);
+}
+function normalizeOperation(entry, context, typeImports, 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);
+	return {
+		bodyChannel,
+		builderAlias,
+		entry,
+		optionTypeName: getClientOptionTypeName(entry.funcName),
+		pathChannel,
+		pathInvocationExpr: pathChannel.present ? `${builderAlias}(options.path)` : `${builderAlias}()`,
+		queryChannel,
+		requestFunction: responseTypeExpr ? requestFunctionNames.json : requestFunctionNames.void,
+		responseTypeExpr,
+		returnTypeExpr: responseTypeExpr ? `Promise<${responseTypeExpr}>` : "Promise<void>"
+	};
+}
+function normalizeParameterChannel(entry, context, location, typeImports) {
+	const parameters = getEffectiveParametersByLocation(entry, location);
+	if (parameters.length === 0) return {
+		present: false,
+		required: false,
+		typeExpr: null
+	};
+	return {
+		present: true,
+		required: hasRequiredChannel(parameters),
+		typeExpr: resolveParameterTypeExpression(entry, context, location, typeImports)
+	};
+}
+function normalizeBodyChannel(entry, context, typeImports) {
+	const typeExpr = resolveRequestBodyTypeExpression(entry, context, typeImports);
+	if (!typeExpr) return {
+		present: false,
+		required: false,
+		typeExpr: null
+	};
+	return {
+		present: true,
+		required: entry.operation.requestBody?.required !== false,
+		typeExpr
+	};
+}
+function resolveRequestBodyTypeExpression(entry, context, typeImports) {
+	const jsonBody = getJsonRequestBody(entry.operation);
+	if (!jsonBody) return null;
+	const alias = resolveSchemaAlias(context, jsonBody.schema, typeImports);
+	if (alias) return alias;
+	return `operations['${entry.operationId}']['requestBody']['content']['application/json']`;
+}
+function resolveResponseTypeExpression(entry, context, typeImports, 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;
+	return `operations['${entry.operationId}']['responses'][${formatStatusKey(successResponse.statusKey)}]['content']['application/json']`;
+}
+function hasSameParameterNames(left, right) {
+	if (left.length !== right.length) return false;
+	const leftNames = left.map((parameter) => parameter.name).sort();
+	const rightNames = right.map((parameter) => parameter.name).sort();
+	return leftNames.every((name, index) => name === rightNames[index]);
+}
+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 (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;
+	}
+	return candidates[0];
+}
+function resolveSchemaAlias(context, schema, typeImports) {
+	const ref = readSchemaRef(schema);
+	if (!ref) return;
+	const schemaName = ref.split("/").pop();
+	if (!schemaName || !context.schemaNames.has(schemaName)) return;
+	typeImports.add(schemaName);
+	return schemaName;
+}
+function readSchemaRef(schema) {
+	if (!schema || typeof schema !== "object") return;
+	const maybeRef = schema.$ref;
+	return typeof maybeRef === "string" ? maybeRef : void 0;
+}
+function renderInlineParameterObject(parameters) {
+	return `{ ${parameters.map((parameter) => {
+		const optionalMarker = parameter.required ? "" : "?";
+		return `${parameter.name}${optionalMarker}: ${renderPrimitiveSchemaType(parameter.schema)}`;
+	}).join("; ")} }`;
+}
+function renderPrimitiveSchemaType(schema) {
+	const type = schema?.type;
+	if (!type) return "unknown";
+	if (Array.isArray(type)) return type.map((memberType) => mapPrimitiveType(memberType)).join(" | ");
+	return mapPrimitiveType(type);
+}
+function mapPrimitiveType(type) {
+	switch (type) {
+		case "integer":
+		case "number": return "number";
+		case "boolean": return "boolean";
+		case "null": return "null";
+		case "string": return "string";
+		default: return "unknown";
+	}
+}
+//#endregion
+//#region src/plugin.ts
+const HTTP_CLIENT_DEFAULTS = {
+	module: "#/integrations/http",
+	jsonFunction: "requestJson",
+	voidFunction: "requestVoid",
+	requestOptionsType: "ApiRequestOptions",
+	omitKeys: [
+		"json",
+		"method",
+		"searchParams",
+		"signal"
+	]
+};
+function resolveHttpClientConfig(config) {
+	return {
+		...HTTP_CLIENT_DEFAULTS,
+		...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) {
+	const { default: openapiTS, astToString } = await import("openapi-typescript");
+	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,
+		group: op.entry.group,
+		pathTypeExpr: op.pathChannel.present ? op.pathChannel.typeExpr : null,
+		strippedPath: op.entry.strippedPath
+	}));
+}
+function createClientRenderModel(model) {
+	return {
+		needsSearchParamsHelper: model.needsSearchParamsHelper,
+		operations: model.operations.map((operation) => ({
+			bodyChannel: operation.bodyChannel,
+			builderAlias: operation.builderAlias,
+			funcName: operation.entry.funcName,
+			group: operation.entry.group,
+			methodUpper: operation.entry.method.toUpperCase(),
+			optionTypeName: operation.optionTypeName,
+			pathChannel: operation.pathChannel,
+			pathInvocationExpr: operation.pathInvocationExpr,
+			queryChannel: operation.queryChannel,
+			requestFunction: operation.requestFunction,
+			responseTypeExpr: operation.responseTypeExpr,
+			returnTypeExpr: operation.returnTypeExpr
+		})),
+		typeImports: model.typeImports
+	};
+}
+function renderGeneratedArtifacts(spec, options, preCollectedOperations) {
+	const pathPrefix = options.pathPrefix ?? "/api/";
+	const stripPrefix = options.stripPrefix ?? true;
+	const httpClient = resolveHttpClientConfig(options.httpClient);
+	const clientModel = buildClientRenderModelFromOperations(preCollectedOperations ?? collectOperations(spec, pathPrefix, stripPrefix), spec, {
+		json: httpClient.jsonFunction,
+		void: httpClient.voidFunction
+	});
+	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)
+	};
+}
+async function generate(root, options) {
+	const inputPath = resolve(root, options.input);
+	const outputDir = resolve(root, options.output);
+	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);
+}
+function openapiCodegen(options) {
+	let root = process.cwd();
+	return {
+		name: "openapi-codegen",
+		enforce: "pre",
+		configResolved(config) {
+			root = config.root;
+		},
+		async buildStart() {
+			await generate(root, options);
+		},
+		configureServer(server) {
+			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.");
+				}
+			});
+		}
+	};
+}
+//#endregion
+export { openapiCodegen, renderGeneratedArtifacts };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "vite-plugin-openapi-codegen",
+  "version": "0.0.3",
+  "description": "Vite plugin that generates typed API clients and route builders from OpenAPI specs",
+  "keywords": [
+    "api-client",
+    "codegen",
+    "openapi",
+    "openapi-typescript",
+    "route-builder",
+    "vite",
+    "vite-plugin",
+    "vite-plus"
+  ],
+  "homepage": "https://github.com/GGGLHHH/vite-plugin-openapi-codegen#readme",
+  "bugs": {
+    "url": "https://github.com/GGGLHHH/vite-plugin-openapi-codegen/issues"
+  },
+  "license": "MIT",
+  "author": "ge Datou (https://github.com/GGGLHHH)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GGGLHHH/vite-plugin-openapi-codegen.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "release": "bumpp --no-verify",
+    "prepublishOnly": "vp run build"
+  },
+  "dependencies": {
+    "openapi-typescript": "^7.13.0",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "bumpp": "^11.0.1",
+    "vite-plus": "^0.1.14"
+  },
+  "peerDependencies": {
+    "vite-plus": ">=0.1.0"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "packageManager": "npm@11.12.0"
+}