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.
        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

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
npm run test
npm run test:watch

# Release new version
npm run release