OpenAPI Generator Plugin

A Vite plugin that watches OpenAPI spec files and auto-generates TypeScript client code during development.

Import

import { openapiClientGeneratorPlugin } from '@zyno-io/vue-foundation/vite-plugins';

Usage

Add the plugin to your Vite config:

// vite.config.ts
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

import { openapiClientGeneratorPlugin } from '@zyno-io/vue-foundation/vite-plugins';

export default defineConfig({
    plugins: [vue(), openapiClientGeneratorPlugin()]
});

The plugin runs only during development (vite serve). It is automatically skipped during production builds.

Prerequisites

Install the code generator package:

yarn add @zyno-io/openapi-client-codegen

Configuration

Create an openapi-specs.json file in your project root. The keys are paths to OpenAPI spec files and the values are output paths or config objects:

{
    "./specs/openapi.yaml": "./src/api-client",
    "./specs/other-api.yaml": {
        "path": "./src/other-client",
        "prefix": "Other"
    }
}

Value Fields

Each entry value can be a simple output path string, or an object:

Field	Type	Description
path	string	Directory where generated TypeScript client is written
prefix	string	Optional prefix for generated types

Dev Overrides

You can create an optional openapi-specs.dev.json to point at a local backend's spec file during development. Keys are the original spec paths from openapi-specs.json, values are the local override paths:

{
    "./specs/openapi.yaml": "../backend/openapi.yaml"
}

When an override is active, the plugin watches the override path (e.g. ../backend/openapi.yaml) instead of the original. When the spec changes, it regenerates the client and copies the file back to the original path (./specs/openapi.yaml), keeping your committed spec in sync.

This is useful when running the backend and frontend simultaneously — the backend regenerates its OpenAPI spec, and the frontend automatically picks up the changes, regenerates the client, and updates the local copy of the spec.

This file should be added to .gitignore.

How It Works

1. On vite serve startup, the plugin calls createWatchfulOpenapiClientGenerators() from @zyno-io/openapi-client-codegen.
2. This reads openapi-specs.json (and openapi-specs.dev.json if present) and sets up file watchers on each spec file.
3. When a spec file changes, the corresponding TypeScript client code is regenerated automatically.
4. When the dev server shuts down, all file watchers are cleaned up.

The startup has a slight delay (250ms) so the generator output does not obscure Vite's startup messages.

Integration with Error Handling

Pair this plugin with configureVfOpenApiClient to get automatic UserError conversion for HTTP 422 responses:

import { configureVfOpenApiClient } from '@zyno-io/vue-foundation';
import { apiClient } from './api-client'; // generated by the plugin

configureVfOpenApiClient(apiClient, {
    onError(err, options) {
        console.error('API error:', err);
        return err;
    }
});

See the OpenAPI helper page for details.