Documentation

OpenAPI Sync is a powerful developer tool that automates the generation of TypeScript types, API clients (Fetch, Axios, React Query, SWR, RTK Query), runtime validation schemas (Zod, Yup, Joi), and endpoint definitions from your OpenAPI specifications in real-time.

Latest Version: 6.2.0 - ship the latest agent-friendly release with CLI, MCP, and cache-aware endpoint workflows

Getting Started with OpenAPI Sync

Duration: 0:10

Learn the basics of OpenAPI Sync and how it can automate your API development workflow.

Watch on YouTube

Installation

Installation & Setup

Duration: 0:10

Step-by-step guide to installing and configuring OpenAPI Sync in your project.

Watch on YouTube

Install OpenAPI Sync using your preferred package manager:

bash

# NPM
npm install openapi-sync

# Yarn
yarn add openapi-sync

# PNPM
pnpm add openapi-sync

# Global Installation
npm install -g openapi-sync

# Direct Usage (No Installation)
npx openapi-sync

⚠️ macOS Big Sur Users: If you encounter an esbuild installation error (Symbol not found: _SecTrustCopyCertificateChain), please install esbuild@0.17.19 first: npm install esbuild@0.17.19 then install openapi-sync. See Troubleshooting for details.

Quick Start

Quick Start Tutorial

Duration: 0:10

Get up and running with OpenAPI Sync in under 5 minutes with this quick start guide.

Watch on YouTube

1. Create Configuration

Create a configuration file in your project root:

json

// openapi.sync.json
{
  "refetchInterval": 5000,
  "folder": "./src/api",
  "api": {
    "petstore": "https://petstore3.swagger.io/api/v3/openapi.json"
  }
}

2. Run Sync Command

bash

npx openapi-sync

3. Use Generated Code

typescript

import { getPetById } from "./src/api/petstore/endpoints";
import { IPet } from "./src/api/petstore/types";

// Use the endpoint URL
const petUrl = getPetById("123"); // Returns: "/pet/123"

// Use the generated types
const pet: IPet = {
  id: 1,
  name: "Fluffy",
  status: "available"
};

Basic Configuration

Duration: 0:10

Learn how to configure OpenAPI Sync with JSON, TypeScript, or JavaScript config files.

Watch on YouTube

OpenAPI Sync supports multiple configuration formats:

openapi.sync.json - JSON format
openapi.sync.ts - TypeScript format
openapi.sync.js - JavaScript format

Configuration Options

Property	Type	Description
refetchInterval	number	Milliseconds between API refetches (dev only)
folder	string	Output directory for generated files
api	Record<string, string>	Map of API names to OpenAPI spec URLs
server	number \| string	Server index or custom server URL

Folder Splitting

Folder Splitting & Organization

Duration: 0:10

Organize your generated code by tags or custom logic for better project structure.

Watch on YouTube

Organize your generated code into folders based on tags or custom logic.

Split by Tags

typescript

folderSplit: {
  byTags: true  // Creates folders like admin/, user/, pet/
}

Custom Folder Logic

typescript

folderSplit: {
  customFolder: ({ method, path, tags, operationId }) => {
    // Admin endpoints go to admin folder
    if (tags?.includes("admin")) return "admin";
    
    // API versioning
    if (path.startsWith("/api/v1/")) return "v1";
    if (path.startsWith("/api/v2/")) return "v2";
    
    // Method-based organization
    if (method === "GET") return "read";
    if (method === "POST" || method === "PUT") return "write";
    
    return null; // Use default structure
  }
}

Generated Structure

text

src/api/
├── petstore/
│   ├── admin/
│   │   ├── endpoints.ts
│   │   └── types.ts
│   ├── user/
│   │   ├── endpoints.ts
│   │   └── types.ts
│   └── pet/
│       ├── endpoints.ts
│       └── types.ts
└── shared.ts

Validation Schemas

Runtime Validation with Zod, Yup & Joi

Duration: 0:10

Generate and use runtime validation schemas for type-safe API requests.

Watch on YouTube

Generate runtime validation schemas using Zod, Yup, or Joi from your OpenAPI specification.

Configuration

typescript

validations: {
  library: "zod",  // "zod" | "yup" | "joi"
  generate: {
    query: true,   // Generate query parameter validations
    dto: true      // Generate request body validations
  },
  name: {
    prefix: "I",
    suffix: "Schema",
    useOperationId: true
  }
}

Installation

bash

# For Zod
npm install zod

# For Yup
npm install yup

# For Joi
npm install joi

Usage Example

typescript

import { IAddPetDTOSchema } from "./src/api/petstore/validation";
import { z } from "zod";

// Validate request body
try {
  const validatedData = IAddPetDTOSchema.parse(req.body);
  // Data is now validated and typed
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error("Validation errors:", error.errors);
  }
}

Express Middleware

typescript

import { Request, Response, NextFunction } from "express";
import { z } from "zod";

export const validate = <T extends z.ZodTypeAny>(schema: T) => {
  return (req: Request, res: Response, next: NextFunction) => {
    try {
      schema.parse(req.body);
      next();
    } catch (error) {
      if (error instanceof z.ZodError) {
        res.status(400).json({
          error: "Validation failed",
          details: error.errors
        });
      }
    }
  };
};

// Usage
import { IAddPetDTOSchema } from "./api/validation";
router.post("/pet", validate(IAddPetDTOSchema), handler);

Custom Code Preservation

Duration: 0:10

Learn how to add custom code that survives regeneration using special markers.

Watch on YouTube

Add your own custom code that will survive when files are regenerated.

Configuration

typescript

customCode: {
  enabled: true,              // Enable custom code preservation
  position: "bottom",         // "top" | "bottom" | "both"
  markerText: "CUSTOM CODE",  // Custom marker text
  includeInstructions: true   // Include helpful instructions
}

Usage

typescript

// endpoints.ts (after generation)
export const getPet = (petId: string) => `/pet/${petId}`;

// 🔒 CUSTOM CODE START
// Add your custom code here - it will be preserved
export const legacyGetPet = (id: string) => `/api/v1/pet/${id}`;

export const buildPetUrl = (petId: string, includePhotos: boolean) => {
  const base = getPet(petId);
  return includePhotos ? `${base}?include=photos` : base;
};
// 🔒 CUSTOM CODE END

export const updatePet = (petId: string) => `/pet/${petId}`;

Endpoint Filtering

Endpoint Filtering & Selection

Duration: 0:10

Filter endpoints by tags, paths, or regex patterns to control what gets generated.

Watch on YouTube

Control which endpoints are included in code generation.

Exclude Endpoints

typescript

endpoints: {
  exclude: {
    // Exclude by tags
    tags: ["deprecated", "internal"],
    
    // Exclude specific endpoints
    endpoints: [
      { path: "/admin/users", method: "DELETE" },
      { regex: "^/internal/.*", method: "GET" },
      { path: "/debug" }  // All methods
    ]
  }
}

Include Only Specific Endpoints

typescript

endpoints: {
  include: {
    // Include only public endpoints
    tags: ["public"],
    
    // Include specific endpoints
    endpoints: [
      { path: "/public/users", method: "GET" },
      { regex: "^/public/.*" }
    ]
  }
}

API Client Generation

Automatically generate fully-typed API clients and hooks for popular libraries directly from your OpenAPI specifications.

Generate clients for Fetch, Axios, React Query, SWR, and RTK Query with full TypeScript support!

API Client Generation Overview

Duration: 0:10

Introduction to generating fully-typed API clients from your OpenAPI specification.

Watch on YouTube

Supported Client Types

fetch - Native browser Fetch API with TypeScript types
axios - Axios client with interceptors and error handling
react-query - React Query/TanStack Query hooks (v4 & v5)
swr - SWR hooks for React
rtk-query - Redux Toolkit Query API slice

Basic Usage

bash

# Generate Fetch client
npx openapi-sync generate-client --type fetch

# Generate Axios client
npx openapi-sync generate-client --type axios

# Generate React Query hooks
npx openapi-sync generate-client --type react-query

# Generate SWR hooks
npx openapi-sync generate-client --type swr

# Generate RTK Query API
npx openapi-sync generate-client --type rtk-query

Filter by Tags or Endpoints

Generate clients for specific endpoints only:

bash

# Filter by tags
npx openapi-sync generate-client --type fetch --tags pets,users

# Filter by endpoint names
npx openapi-sync generate-client --type axios --endpoints getPetById,createPet

# Generate for specific API
npx openapi-sync generate-client --type react-query --api petstore

# Specify output directory
npx openapi-sync generate-client --type swr --output ./src/clients

# Set base URL
npx openapi-sync generate-client --type fetch --base-url https://api.example.com

React Query Example

Complete example using React Query hooks:

typescript

// 1. Generate the client
// npx openapi-sync generate-client --type react-query

// 2. Setup in your app
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import apiClient from "./api/petstore/client/client";

// Configure API client
apiClient.updateConfig({
  baseURL: "https://api.example.com",
  headers: {
    Authorization: "Bearer your-auth-token",
  },
});

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourComponent />
    </QueryClientProvider>
  );
}

// 3. Use in components
import { useGetPetById, useCreatePet } from "./api/petstore/client/hooks";

function PetDetails({ petId }: { petId: string }) {
  // Query hook for GET requests
  const { data, isLoading, error } = useGetPetById({ petId });

  // Mutation hook for POST/PUT/PATCH/DELETE
  const createPet = useCreatePet({
    onSuccess: (newPet) => {
      console.log("Pet created:", newPet);
    },
  });

  const handleCreate = () => {
    createPet.mutate({
      data: {
        name: "Fluffy",
        species: "cat",
      },
    });
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>{data?.name}</h1>
      <p>Status: {data?.status}</p>
      <button onClick={handleCreate}>Create New Pet</button>
    </div>
  );
}

Fetch Client Example

typescript

import { setApiConfig, getPetById, createPet } from "./api/petstore/client";

// Configure the client
setApiConfig({
  baseURL: "https://api.example.com",
  auth: { token: "your-token" },
  headers: {
    "X-Custom-Header": "value",
  },
});

// Use the client
async function fetchPet(petId: string) {
  try {
    const pet = await getPetById({ petId });
    console.log("Pet:", pet);
  } catch (error) {
    if (error instanceof ApiError) {
      console.error("API Error:", error.statusCode, error.response);
    }
  }
}

async function addNewPet() {
  const newPet = await createPet({
    data: {
      name: "Max",
      species: "dog",
      age: 3,
    },
  });
  console.log("Created:", newPet);
}

Axios Client Example

typescript

import apiClient from "./api/petstore/client";

// Configure the client
apiClient.updateConfig({
  baseURL: "https://api.example.com",
  timeout: 10000,
  headers: {
    "X-App-Version": "1.0.0",
    Authorization: "Bearer your-auth-token",
  },
});

// Use the client
async function example() {
  // GET request
  const pet = await apiClient.getPetById({ petId: "123" });
  
  // POST request
  const newPet = await apiClient.createPet({
    data: {
      name: "Buddy",
      species: "dog",
    },
  });
  
  // PUT request
  await apiClient.updatePet(
    { petId: "123" },
    { name: "Buddy Updated" }
  );
  
  // DELETE request
  await apiClient.deletePet({ petId: "123" });
}

SWR Hooks Example

typescript

import { useGetPetById, useCreatePet } from "./api/petstore/client/hooks";

function PetProfile({ petId }: { petId: string }) {
  // SWR automatically handles caching, revalidation, and more
  const { data, error, isLoading, mutate } = useGetPetById({ petId });

  const { trigger, isMutating } = useCreatePet();

  const handleCreate = async () => {
    try {
      const newPet = await trigger({
        arg: {
          data: {
            name: "Charlie",
            species: "cat",
          },
        },
      });
      // Revalidate the pet list
      mutate();
    } catch (err) {
      console.error("Failed to create pet:", err);
    }
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error loading pet</div>;

  return (
    <div>
      <h2>{data?.name}</h2>
      <button onClick={handleCreate} disabled={isMutating}>
        {isMutating ? "Creating..." : "Create New Pet"}
      </button>
    </div>
  );
}

RTK Query Example

typescript

// 1. Setup store
import { configureStore } from "@reduxjs/toolkit";
import { apiApi } from "./api/petstore/client/api";

export const store = configureStore({
  reducer: {
    [apiApi.reducerPath]: apiApi.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(apiApi.middleware),
});

// 2. Use in components
import { useGetPetByIdQuery, useCreatePetMutation } from "./api/petstore/client/api";

function PetCard({ petId }: { petId: string }) {
  const { data, isLoading, error } = useGetPetByIdQuery({ 
    params: { petId } 
  });
  
  const [createPet, { isLoading: isCreating }] = useCreatePetMutation();

  const handleCreate = async () => {
    try {
      await createPet({
        data: {
          name: "Luna",
          species: "cat",
        },
      }).unwrap();
      alert("Pet created!");
    } catch (err) {
      console.error("Failed:", err);
    }
  };

  return (
    <div>
      {isLoading && <div>Loading...</div>}
      {error && <div>Error!</div>}
      {data && (
        <div>
          <h3>{data.name}</h3>
          <p>{data.species}</p>
        </div>
      )}
      <button onClick={handleCreate} disabled={isCreating}>
        Create Pet
      </button>
    </div>
  );
}

Generated File Structure

text

api/
└── petstore/
    ├── client/
    │   ├── client.ts      # Base API client
    │   ├── hooks.ts       # React Query/SWR hooks
    │   ├── api.ts         # RTK Query API (if applicable)
    │   ├── index.ts       # Exports
    │   └── README.md      # Usage documentation
    ├── endpoints.ts
    ├── types/
    │   ├── index.ts
    │   └── shared.ts
    └── validations.ts

Configuration Options

typescript

// openapi.sync.ts
import { IConfig } from "openapi-sync/types";

const config: IConfig = {
  folder: "./src/api",
  api: {
    petstore: "https://petstore3.swagger.io/api/v3/openapi.json",
  },
  // Client generation configuration
  clientGeneration: {
    enabled: true,
    type: "react-query",
    baseURL: "https://api.example.com",
    tags: ["pets", "users"],  // Optional: filter by tags
    endpoints: ["getPetById"], // Optional: specific endpoints
    auth: {
      type: "bearer",
      in: "header",
    },
    errorHandling: {
      generateErrorClasses: true,
    },
    reactQuery: {
      version: 5,
      mutations: true,
      infiniteQueries: false,
    },
  },
};

export default config;

Custom Code Preservation

Generated clients preserve your custom code during regeneration:

typescript

// client.ts (Generated)

// Auto-generated client code...

// ============================================================
// 🔒 CUSTOM CODE START
// Add your custom code below this line
// This section will be preserved during regeneration
// ============================================================

// Your custom helper functions
export function buildPaginatedUrl(
  baseUrl: string,
  page: number,
  limit: number
) {
  return `${baseUrl}?page=${page}&limit=${limit}`;
}

// Custom interceptors
export function setupCustomInterceptors() {
  // Your custom logic
}

// 🔒 CUSTOM CODE END
// ============================================================

CLI Options Reference

Option	Description	Example
--type, -t	Client type to generate (required)	fetch, axios, react-query, swr, rtk-query
--api, -a	Specific API from config	--api petstore
--tags	Filter by endpoint tags	--tags pets,users
--endpoints, -e	Filter by endpoint names	--endpoints getPetById,createPet
--output, -o	Output directory	--output ./src/clients
--base-url, -b	Base URL for requests	--base-url https://api.example.com

New in v5.0.0: All client generators now include comprehensive inline documentation, better ESLint compliance, and improved folder splitting support!

RTK Query Enhancements (v5.0.0)

Simplified Redux Store Setup

When using folder splitting, RTK Query now generates an apis.ts file with a helper object that makes Redux store configuration incredibly simple:

typescript

// Before v5.0.0 (Complex setup)
import { configureStore } from '@reduxjs/toolkit';
import { petsApi } from './pets/api';
import { usersApi } from './users/api';
import { ordersApi } from './orders/api';

export const store = configureStore({
  reducer: {
    [petsApi.reducerPath]: petsApi.reducer,
    [usersApi.reducerPath]: usersApi.reducer,
    [ordersApi.reducerPath]: ordersApi.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware()
      .concat(petsApi.middleware)
      .concat(usersApi.middleware)
      .concat(ordersApi.middleware),
});

typescript

// After v5.0.0 (Simple setup!)
import { configureStore } from '@reduxjs/toolkit';
import { setupApiStore } from './api/petstore/apis';

export const store = configureStore({
  reducer: setupApiStore.reducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(setupApiStore.middleware),
});

// That's it! All API slices are automatically configured ✨

Unique Reducer Paths

Each API slice now has a unique reducerPath based on its folder name, preventing conflicts:

typescript

// Generated pets/api.ts
const petsApi = createApi({
  reducerPath: 'petsApi',  // ✅ Unique!
  // ...
});

// Generated users/api.ts
const usersApi = createApi({
  reducerPath: 'usersApi',  // ✅ Unique!
  // ...
});

// No more "Duplicate property" TypeScript errors!

Default Exports for Better Imports

API slices now export as default, making imports cleaner:

typescript

// Clean default import
import petsApi from './pets/api';
import { useGetPetsQuery } from './pets/api';

// Or use the aggregated apis.ts
import { petsApi, useGetPetsQuery } from './apis';

SWR Improvements (v5.0.0)

Fixed Mutation Type Errors

SWR mutation hooks now have correct TypeScript types, fixing the double-nesting issue:

typescript

// v5.0.0 - Correct types! ✅
export function useCreatePet(
  config?: SWRMutationConfiguration<
    Pet,
    Error,
    string,
    { data: PetRequest }  // Correct: single level
  >
) {
  return useSWRMutation(
    'createPet',
    async (_, { arg }: { arg: { data: PetRequest } }) => {
      return apiClient.createPet(arg);
    },
    config
  );
}

// Usage - works perfectly!
const { trigger } = useCreatePet();
await trigger({ arg: { data: { name: 'Fluffy' } } });

Comprehensive Inline Documentation

Every generated SWR hooks file now includes 230+ lines of usage examples and patterns:

typescript

/**
 * SWR Hooks - Complete Usage Guide
 * 
 * ## Quick Start
 * 
 * 1. Configure SWR globally:
 * ```typescript
 * <SWRConfig value={{ revalidateOnFocus: false }}>
 *   {children}
 * </SWRConfig>
 * ```
 * 
 * ## Examples
 * 
 * ### Reading Data (GET)
 * ```typescript
 * const { data, error, isLoading } = useGetPets();
 * ```
 * 
 * ### Creating Data (POST)
 * ```typescript
 * const { trigger, isMutating } = useCreatePet();
 * await trigger({ arg: { data: { name: 'Luna' } } });
 * ```
 * 
 * ### Optimistic Updates
 * ```typescript
 * revalidate({ ...data, name: newName }, false);
 * await trigger({ arg: { ... } });
 * await revalidate(); // Sync with server
 * ```
 * 
 * [... 200+ more lines of examples ...]
 */

Fetch Client Fixes (v5.0.0)

Fixed Naming Conflicts

Endpoint imports are now automatically aliased to prevent naming conflicts:

typescript

// Generated imports (aliased to avoid conflicts)
import {
  getPets as getPets_endpoint,
  getPetById as getPetById_endpoint,
  createPet as createPet_endpoint,
} from './endpoints';

// Generated functions (no conflict!)
export async function getPets() {
  const _url = getPets_endpoint;  // Uses aliased import
  return fetchAPI(_url, { method: 'GET' });
}

export async function getPetById(params: { url: { id: string } }) {
  const _url = getPetById_endpoint(params.url.id);  // Uses aliased import
  return fetchAPI(_url, { method: 'GET' });
}

ESLint-Compliant Default Exports

Default exports now use named variables, satisfying ESLint rules:

typescript

// v5.0.0 - ESLint compliant! ✅
const apiClient = {
  setApiConfig,
  getPets,
  getPetById,
  createPet,
};

export default apiClient;

// No more "Assign object to variable" ESLint warnings!

File Organization Improvements (v5.0.0)

Non-Folder-Split Mode

When folder splitting is disabled, files are now generated directly at the root level:

text

api/
└── petstore/
    ├── clients.ts       # All API client functions
    ├── hooks.ts         # All React Query/SWR hooks  
    ├── endpoints.ts     # Endpoint definitions
    ├── types.ts         # TypeScript types
    └── validations.ts   # Validation schemas

# Clean, simple structure for smaller APIs!

Folder-Split Mode

With folder splitting, each tag gets its own folder with complete isolation:

text

api/
└── petstore/
    ├── clients.ts       # Aggregates all clients (Fetch/Axios)
    ├── hooks.ts         # Aggregates all hooks (React Query/SWR)
    ├── apis.ts          # Aggregates all APIs (RTK Query) + setupApiStore
    ├── pets/
    │   ├── client.ts    # Pet-specific client
    │   ├── hooks.ts     # Pet-specific hooks
    │   ├── api.ts       # Pet-specific RTK Query API
    │   ├── types.ts     # Pet-specific types
    │   └── endpoints.ts # Pet-specific endpoints
    └── users/
        ├── client.ts
        ├── hooks.ts
        ├── api.ts
        ├── types.ts
        └── endpoints.ts

# Perfect for large APIs with many endpoints!

💡 Migration Tip: To get all these improvements, simply regenerate your clients:

bash

npx openapi-sync generate-client --type [your-type]

All improvements are backwards compatible - your existing code will continue to work!

CLI Usage

CLI Commands & Options

Duration: 0:10

Master the OpenAPI Sync CLI with all available commands and options.

Watch on YouTube

bash

# Sync API types and endpoints
npx openapi-sync

# Generate API client
npx openapi-sync generate-client --type react-query

# Run with custom refetch interval
npx openapi-sync --refreshinterval 30000
npx openapi-sync -ri 30000

# Get help
npx openapi-sync --help
npx openapi-sync generate-client --help

CLI Improvements (v5.0.0)

CLI Arguments Override Config

CLI options now correctly override configuration file settings:

bash

# Config file says type: "fetch"
# But CLI argument takes precedence:
npx openapi-sync generate-client --type rtk-query

# Result: Generates RTK Query (not Fetch) ✅

# This works for all options:
npx openapi-sync generate-client \
  --type swr \
  --base-url https://api.example.com \
  --tags pets,users

# CLI values override config values!

Streamlined Interactive Setup

The interactive setup wizard is now simpler - selecting folder splitting automatically enables tag-based organization:

bash

# npx openapi-sync init

? Organize generated code into folders by OpenAPI tags? Yes
# ✅ Automatically enables byTags: true
# (No extra question needed!)

? Generate API client code? Yes
? Which client type would you like? React Query
# ... continues with setup

Machine-Readable Output (CI/CD & Agent-Safe)

All commands support --json for structured stdout output and --silent to suppress all logs. Ideal for scripting, CI pipelines, and AI agent integrations:

bash

# Sync and get a structured JSON result
npx openapi-sync --json

# Validate config without writing files
npx openapi-sync validate --json

# List all endpoints as JSON
npx openapi-sync list-endpoints --json

# Generate client with JSON output (great for agents)
npx openapi-sync generate-client --type react-query --json

# Silent mode (no stdout noise) — exit code tells you the result
npx openapi-sync --silent && echo "Sync OK!"

Tip: The --json flag implies --silent. The process exit code is 0 on success and 1 on failure, so it works naturally in shell pipelines and CI checks.

Programmatic Usage

Programmatic API Usage

Duration: 0:10

Use OpenAPI Sync programmatically in your Node.js scripts and build tools.

Watch on YouTube

typescript

import { Init } from "openapi-sync";

// Initialize with default config
await Init();

// Initialize with custom options
await Init({
  refetchInterval: 30000
});

// With error handling
try {
  await Init({
    refetchInterval: process.env.NODE_ENV === "development" ? 5000 : 0
  });
  console.log("API types synchronized successfully");
} catch (error) {
  console.error("Failed to sync API types:", error);
}

AI Agent Integration (MCP)

OpenAPI Sync ships with a built-in Model Context Protocol (MCP) server. This lets AI assistants like Claude Desktop, Cursor, GitHub Copilot, and other MCP-compatible agents safely call sync operations, browse endpoints with pagination and path filters, inspect deep endpoint details, and read generated TypeScript declarations — no shell scripts or custom wrappers needed.

🤖 How it works: Start the MCP server with npx openapi-sync-mcp and configure your AI client to connect to it. The agent can then trigger syncs, generate clients, validate configs, and list endpoints — all with full type-safety.

Setup for Claude Desktop

Add the following to your Claude Desktop configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "openapi-sync": {
      "command": "npx",
      "args": ["-y", "openapi-sync-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Setup for Cursor

Create or update .cursor/mcp.json in your project root:

json

{
  "mcpServers": {
    "openapi-sync": {
      "command": "npx",
      "args": ["-y", "openapi-sync-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Available MCP Tools

Once connected, the agent has access to these tools:

Tool	Description
openapi_sync_sync	Run the main sync command — generates types, clients, and endpoints
openapi_sync_validate	Validate your config and OpenAPI specs without writing any files
openapi_sync_list_endpoints	List discovered endpoints with tags, pagination, path filtering, and optional cache reuse
openapi_sync_get_endpoint_details	Return the full stored schema for a single endpoint by operationId or name
openapi_sync_read_generated_type	Read the exact generated TypeScript interface or type declaration
openapi_sync_generate_client	Generate a typed API client for Fetch, Axios, React Query, SWR, or RTK Query
openapi_sync_init	Non-interactively initialise a new openapi-sync configuration

Example Agent Prompt

Once the MCP server is running, you can ask your AI agent:

bash

# Ask Claude or Cursor:
"Sync my OpenAPI types, list the pet endpoints, inspect getPetById, and generate a React Query client"

# The agent will:
# 1. Call 'openapi_sync_sync' to pull the latest spec
# 2. Call 'openapi_sync_list_endpoints' with pagination/path filters
# 3. Call 'openapi_sync_get_endpoint_details' for the selected endpoint
# 4. Call 'openapi_sync_read_generated_type' for the related type
# 5. Call 'openapi_sync_generate_client' with --type react-query
# 6. Report back the result as structured JSON

Troubleshooting

Common Issues & Troubleshooting

Duration: 0:10

Learn how to debug and resolve common issues when using OpenAPI Sync.

Watch on YouTube

Configuration File Not Found

Error: No config found

Solution: Ensure you have one of these files in your project root:openapi.sync.json, openapi.sync.ts, or openapi.sync.js

Network Timeout Errors

Error: timeout of 60000ms exceeded

Solution: The tool includes automatic retry with exponential backoff. Check your internet connection and verify the OpenAPI spec URL is accessible.

TypeScript Compilation Errors

Error: Cannot find module './src/api/petstore/types'

Solution: Ensure the sync process completed successfully and check that the folder path in config is correct.

macOS Big Sur (11.x) - esbuild Installation Error

Error: dyld: Symbol not found: _SecTrustCopyCertificateChain

Cause: The default esbuild version requires macOS 12.0+ APIs that aren't available in Big Sur (darwin 20.x).

Solution 1: Install compatible esbuild first:

bash

# Install compatible esbuild first
npm install esbuild@0.17.19

# Then install openapi-sync
npm install openapi-sync

Solution 2: Add an override to your package.json:

json

{
  "overrides": {
    "esbuild": "0.17.19"
  }
}

Note: This issue only affects macOS Big Sur. Users on macOS 12+ are not affected and will get the latest esbuild version automatically.

API Reference

Init(options?: InitOptions)

Initializes OpenAPI sync with the specified configuration.

typescript

import { Init } from "openapi-sync";

await Init({ 
  refetchInterval: 10000 
});

Exported Types

typescript

import {
  IConfig,
  IOpenApiSpec,
  IOpenApSchemaSpec,
  IConfigReplaceWord,
  IConfigExclude,
  IConfigInclude,
  IConfigDoc
} from "openapi-sync/types";

Changelog

Track the evolution of OpenAPI Sync with detailed release notes and version history.

v6.2.0

LATEST2026-07-14

ship the latest agent-friendly release with CLI, MCP, and cache-aware endpoint workflows

add richer endpoint discovery, pagination, filtering, and deeper endpoint inspection for AI agents
expand generated-type inspection and MCP tooling for faster local debugging and automation

v6.1.1

2026-07-14

add cache-aware endpoint reuse for list-endpoints and generate-client workflows

v6.1.0

2026-07-03

update Open Collective link to use the correct project handle in README files

v6.0.0

2024-01-01

Major bump for new architecture and LLM agent integration

v5.0.7

2024-01-01

Update dependencies and fix minor bugs

📖 Full Changelog: For complete release notes and detailed changes, visit the dedicated Changelog page.