Nuxt Typesafe OpenAPI Fetch wrapper

Generates a typesafe fetch client for Nuxt and Nitro using Openapi-ts.

Usage

Install the module:

npx nuxi module add nuxt-openapi-wrapper

Configure the api clients:

export default defineNuxtConfig({
  modules: ['nuxt-openapi-wrapper'],
  openAPIWrapper: {
    // config options for openAPI-ts
    openApiTsConfig: {},
    apis: {
      github: {
        baseUrl: 'https://api.github.com',
        // no explicit openAPI document. Will look for an openapi.{json,yaml} in the ./openapi/github directory
      },
      gitlab: {
        baseUrl: 'https://gitlab.com',
        // explicit openAPI document.
        // also supports array. Tries fetching documents in order of array.
        openApi:
          'https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/api/openapi/openapi.yaml?inline=false',
      },
    },
  },
});

That's it! You can now use Nuxt OpenAPI wrapper in your Nuxt app ✨

const x = await $fetchGithub('/advisories/{ghsa_id}' /* auto completion! */, {
  pathParams: {
    // support for path parameters!
    ghsa_id: '2', // typesafety!
  },
});

console.log(x.description); // typesafe response type!

Customizing the client

Often you want to customize the client, e.g. so it always adds an authentication header to requests.

Disable auto import for the base client

export default defineNuxtConfig({
  modules: ['nuxt-openapi-wrapper'],
  openAPIWrapper: {
    apis: {
      github: {
        baseUrl: 'https://api.github.com',
        clients: { nuxt: { autoImport: false }}
        ...

Add a new ts file to your composables folder, e.g. ./composables/githubClient.ts.

// import the base client explicitly
import {
  $fetchGithub as _$fetchGithub,
  useGithubFetch as _useGithubFetch,
  useLazyGithubFetch as _useLazyGithubFetch,
} from '#openapi-wrapper';

// you might need to add // @ts-ignore error
export const $fetchGithub: typeof _$fetchGithub = (path, opts?) => {
  // customize the request
  opts ??= {};

  opts.onRequest = (ctx) =>
    ctx.options.headers.append('Authorization', 'Bearer 1234');

  opts.onResponse = (ctx) => console.log('response!');

  return _$fetchGithub(path, opts);
};

// Do the same for useGithubFetch and useLazyGithubFetch

You can also create a custom Nitro fetch client. E.g. by creating a ./server/utils/githubClient.ts file.

Nuxt composable example

Nitro utils example

Caching generated OpenAPI types

Caching is disabled by default. Enable it for all APIs, then override or disable it per API:

export default defineNuxtConfig({
  openAPIWrapper: {
    openApiTsCache: {
      // Root directory; client-specific subdirectory is added automatically.
      directory: 'node_modules/.cache/nuxt-openAPI-wrapper',
      // Optional extra invalidation token. Bump when custom function behavior changes.
      version: 'team-api-v1',
    },
    apis: {
      github: {
        baseUrl: 'https://api.github.com',
        openApiTsCache: {
          version: 2,
          // Suppress warning if openApiTsConfig contains function values.
          suppressFunctionWarning: true,
        },
      },
      gitlab: {
        baseUrl: 'https://gitlab.com',
        openApiTsCache: false,
      },
    },
  },
});

Set openApiTsCache: true to use defaults. A per-API object inherits module settings and overrides selected fields; per-API false disables caching. Relative directory values resolve from Nuxt rootDir; the API name is appended so each client gets its own latest cache record. Default directory is node_modules/.cache/nuxt-openAPI-wrapper.

Cache keys include this library, openapi-typescript, TypeScript, and Redocly versions; optional version; resolved openApiTsConfig values; and root plus transitive $ref document identities. Function-valued config entries are omitted from the key. A warning explains this when caching is enabled; bump version whenever function behavior changes, or set suppressFunctionWarning: true to silence it.

Local and inline documents use content hashes. HTTP documents use response ETags when present, otherwise content hashes. Cache hits skip openapi-typescript generation, but source freshness still needs to be checked, so remote documents may still be fetched. When MCP schema exposure is enabled, cache record also stores bundled schema for MCP tools. Cache files can therefore contain generated API declarations and schema data; keep this in mind when overriding directory to a git-tracked path. Default path sits under ignored node_modules. For APIs configured with multiple fallback sources, only the first source is cached; when a fallback source is used, its output is generated fresh and not cached.

MCP Integration (AI Agent Support)

This module integrates with nuxt-mcp-dev to expose your OpenAPI schemas as MCP (Model Context Protocol) tools. This allows AI agents like Claude to query your API schemas during development.

Enabling MCP

MCP tools are automatically enabled when nuxt-mcp-dev is installed. You can explicitly control this behavior:

export default defineNuxtConfig({
  modules: ['nuxt-openapi-wrapper', 'nuxt-mcp-dev'],
  openAPIWrapper: {
    // Enable/disable MCP tools for all APIs (default: true when nuxt-mcp-dev is installed)
    exposeToMcp: true,
    apis: {
      github: {
        baseUrl: 'https://api.github.com',
        // Override at the API level
        exposeToMcp: false,
      },
      gitlab: {
        baseUrl: 'https://gitlab.com',
        // This API will use the module-level setting (true)
      },
    },
  },
});

Available MCP Tools

When enabled, the following tools are registered for AI agents to query your OpenAPI schemas. All tools require schemaName to select which API schema to query.

Tool	Optional Parameters	Description
nuxt-openAPI-wrapper__get-openAPI-schema	-	Gets the entire OpenAPI schema
nuxt-openAPI-wrapper__get-openAPI-schema-paths	pathRegex, supportedHTTPMethods	Gets API paths, filtered by regex and/or HTTP methods
nuxt-openAPI-wrapper__get-openAPI-schema-webhooks	webhookNameRegex	Gets webhooks, filtered by name regex
nuxt-openAPI-wrapper__get-openAPI-schema-security	schemeNameRegex	Gets security schemes and global security requirements
nuxt-openAPI-wrapper__get-openAPI-schema-tags	tagNameRegex	Gets tags, filtered by name regex
nuxt-openAPI-wrapper__get-openAPI-schema-externalDocs	-	Gets external documentation links
nuxt-openAPI-wrapper__get-openAPI-schema-extensions	extensionNameRegex	Gets extension fields (x-*)
nuxt-openAPI-wrapper__get-openAPI-schema-components-schemas	schemaNameRegex	Gets component schemas
nuxt-openAPI-wrapper__get-openAPI-schema-components-responses	responseNameRegex	Gets component responses
nuxt-openAPI-wrapper__get-openAPI-schema-components-parameters	parameterNameRegex	Gets component parameters
nuxt-openAPI-wrapper__get-openAPI-schema-components-examples	exampleNameRegex	Gets component examples
nuxt-openAPI-wrapper__get-openAPI-schema-components-requestBodies	requestBodyNameRegex	Gets component request bodies
nuxt-openAPI-wrapper__get-openAPI-schema-components-headers	headerNameRegex	Gets component headers
nuxt-openAPI-wrapper__get-openAPI-schema-components-links	linkNameRegex	Gets component links
nuxt-openAPI-wrapper__get-openAPI-schema-components-callbacks	callbackNameRegex	Gets component callbacks
nuxt-openAPI-wrapper__get-openAPI-schema-components-pathItems	pathItemNameRegex	Gets component path items
nuxt-openAPI-wrapper__write-openAPI-schema	overwrite	Writes the schema to absoluteFilePath (required)

All regex parameters are case-insensitive. The supportedHTTPMethods parameter accepts an array of lowercase HTTP methods (e.g., ["get", "post"]).

Contribution

Local development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest (unit, type and e2e tests)
npm run test
npm run test:watch

# Unit and type tests with coverage thresholds / e2e tests only
npm run test:coverage
npm run test:e2e

# Type check the module and the playground
npm run test:types

# Regenerate the type test fixture after an openapi-typescript upgrade
UPDATE_FIXTURES=1 npx vitest run test/generated-types.test.ts

# Release new version
npm run release