Sync Your APIEffortlessly

# Launch the interactive setup wizard
npx openapi-sync init

# The wizard will guide you through:
# ✓ Configuration format (TypeScript/JSON/JavaScript)
# ✓ API specification source (URL or local file)
# ✓ Folder organization (split by tags automatically)
# ✓ Client generation (Fetch, Axios, React Query, SWR, RTK Query)
# ✓ Validation library (Zod, Yup, Joi)
# ✓ Custom code preservation
# ✓ Type naming preferences
# ✓ Endpoint filtering
# ✓ Documentation options

# Creates openapi.sync.ts with all your preferences

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

// Run sync command
// npx openapi-sync

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

const config: IConfig = {
  folder: "./src/api",
  api: {
    myapi: "https://api.example.com/openapi.json"
  },
  validations: {
    library: "zod",
    generate: {
      query: true,
      dto: true
    }
  }
};

export default config;

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);
  }
}

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

# Usage
import apiClient from "./api/petstore/clients";

// Configure the client
apiClient.setApiConfig({
  baseURL: "https://api.example.com",
  headers: { Authorization: "Bearer token" },
});

// Make type-safe requests
const pet = await apiClient.getPetById({ 
  url: { petId: "123" } 
});

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

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

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

// Axios interceptors available
const response = await apiClient.getPetById({ 
  url: { petId: "123" } 
});

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

# Usage in React component
import { useGetPetById, useCreatePet } from "./api/petstore/hooks";

function PetDetails({ petId }) {
  const { data, isLoading } = useGetPetById({
    url: { petId },
    query: { includeOwner: true },
  });

  const createPet = useCreatePet({
    onSuccess: () => console.log("Pet created!"),
  });

  return <div>{data?.name}</div>;
}

# Generate SWR hooks (230+ lines of inline docs)
npx openapi-sync generate-client --type swr

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

function PetComponent({ petId }) {
  // GET request with SWR
  const { data, error, isLoading } = useGetPetById({
    url: { petId },
  });

  // Mutation with optimistic updates
  const { trigger } = useCreatePet({
    onSuccess: () => mutate("/pets"),
  });

  return <div>{data?.name}</div>;
}

# Generate RTK Query API (with setupApiStore helper)
npx openapi-sync generate-client --type rtk-query

# Simplified Redux store setup (5 lines instead of 15!)
import { setupApiStore } from "./api/petstore/apis";

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

// Use in components
import { useGetPetByIdQuery } from "./api/petstore/pets/apis";

function Pet({ petId }) {
  const { data } = useGetPetByIdQuery({ url: { petId } });
  return <div>{data?.name}</div>;
}

# Generate client for specific tags
npx openapi-sync generate-client --type fetch --tags pets,users

# Generate client for specific endpoints
npx openapi-sync generate-client \
  --type axios \
  --endpoints getPetById,createPet,updatePet

# Generate with custom output directory
npx openapi-sync generate-client \
  --type react-query \
  --output ./src/clients \
  --base-url https://api.example.com

// openapi.sync.json
{
  "refetchInterval": 5000,  // Sync every 5 seconds
  "folder": "./src/api",
  "api": {
    "petstore": "https://api.example.com/openapi.json"
  }
}

// Run in watch mode
// npx openapi-sync

// Output:
// ✓ Syncing petstore...
// ✓ Changes detected - regenerating types...
// ✓ Generated 15 endpoints, 25 types
// ⏱ Next sync in 5 seconds...

// openapi.sync.ts
export default (): IConfig => {
  const isDev = process.env.NODE_ENV === "development";
  
  return {
    refetchInterval: isDev ? 5000 : 0,  // Only sync in dev
    folder: "./src/api",
    api: {
      myapi: isDev 
        ? "http://localhost:3000/openapi.json"
        : "https://api.example.com/openapi.json"
    }
  };
};

// openapi.sync.ts
const config: IConfig = {
  folder: "./src/api",
  api: {
    myapi: "https://api.example.com/openapi.json"
  },
  folderSplit: {
    byTags: true  // Auto-enabled in wizard!
  }
};

// Generated structure:
// api/
//   petstore/
//     pets/        ← Tag-based folder
//     users/       ← Tag-based folder
//     apis.ts      ← RTK Query aggregator (v5.0.0)
//     clients.ts   ← Fetch/Axios aggregator
//     hooks.ts     ← React Query/SWR aggregator

folderSplit: {
  customFolder: ({ method, path, tags }) => {
    // Admin endpoints
    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") return "create";
    
    return null; // Use default
  }
}

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
    ]
  }
}

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

types: {
  name: {
    prefix: "I",
    useOperationId: true,
    format: (source, data, defaultName) => {
      if (source === "shared") {
        return `${data.name}Type`;
      }
      if (source === "endpoint" && data.operationId) {
        return `${data.operationId}${data.type}`;
      }
      return defaultName;
    }
  }
}

endpoints: {
  value: {
    type: "object",
    includeServer: true
  }
}

// Generated output:
export const getPetById = {
  method: "GET",
  operationId: "getPetById",
  url: (petId: string) => `/pet/${petId}`,
  tags: ["pet"]
};

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

// 🔒 CUSTOM CODE START
// Add your custom endpoints here
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

# Config file specifies react-query, but CLI overrides
npx openapi-sync generate-client --type rtk-query

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

# Override output directory
npx openapi-sync generate-client \
  --type axios \
  --output ./custom/path

# All CLI args now take precedence over config file!

// openapi.sync.ts
const config: IConfig = {
  folder: "./src/api",
  api: {
    "users": "https://users-api.example.com/openapi.json",
    "products": "https://products-api.example.com/openapi.json",
    "orders": "https://orders-api.example.com/openapi.json"
  },
  folderSplit: { byTags: true }
};

// Generate clients for specific API
// npx openapi-sync generate-client --type fetch --api users
// npx openapi-sync generate-client --type rtk-query --api products

// openapi.sync.ts
export default (): IConfig => {
  const env = process.env.NODE_ENV || "development";
  
  const baseConfig: IConfig = {
    refetchInterval: env === "development" ? 5000 : 0,
    folder: "./src/api",
    api: {}
  };
  
  if (env === "development") {
    baseConfig.api = {
      "local": "http://localhost:3000/openapi.json"
    };
  } else {
    baseConfig.api = {
      "prod": "https://api.example.com/openapi.json"
    };
  }
  
  return baseConfig;
};

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

const config: IConfig = {
  refetchInterval: 5000,
  folder: "./src/api",
  api: {
    petstore: "https://petstore3.swagger.io/api/v3/openapi.json"
  },
  
  // Client generation (v5.0.0)
  clientGeneration: {
    type: "react-query",
    baseURL: "https://api.example.com",
  },
  
  // Folder splitting
  folderSplit: { byTags: true },
  
  // Type naming
  types: {
    name: {
      prefix: "I",
      useOperationId: true,
    }
  },
  
  // Endpoint filtering
  endpoints: {
    exclude: { tags: ["deprecated"] },
    doc: { showCurl: true }
  },
  
  // Validation
  validations: {
    library: "zod",
    generate: { query: true, dto: true }
  }
};

export default config;

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);