openapi-sync 4.0.1 → 5.0.0

package/README.md

@@ -4,19 +4,31 @@
 
 # OpenAPI Sync
 
-**OpenAPI Sync** is a powerful developer tool that automates the synchronization of your API documentation with your codebase using OpenAPI (formerly Swagger) specifications. It generates TypeScript types, endpoint definitions, runtime validation schemas (Zod, Yup, Joi), and comprehensive documentation from your OpenAPI schema—ensuring type safety from API specification to runtime validation.
+**OpenAPI Sync** is a powerful developer tool that automates the synchronization of your API documentation with your codebase using OpenAPI (formerly Swagger) specifications. It generates TypeScript types, fully-typed API clients (Fetch, Axios, React Query, SWR, RTK Query), endpoint definitions, runtime validation schemas (Zod, Yup, Joi), and comprehensive documentation from your OpenAPI schema—ensuring type safety from API specification through client implementation to runtime validation.
 
 > 📘 **[Full documentation available at openapi-sync.com](https://openapi-sync.com)**
 
 ## Features
 
-- 🔄 **Real-time API Synchronization** - Automatically syncs OpenAPI specs from remote URLs
-- 📝 **Automatic Type Generation** - Generates TypeScript interfaces for all endpoints
-- 🔧 **Highly Configurable** - Customizable naming, filtering, and folder organization
-- 🛡️ **Enterprise Ready** - Error handling, validation, and state persistence
-- 🔐 **Runtime Validation** - Generate Zod, Yup, or Joi schemas from OpenAPI specs
-- 📚 **Rich Documentation** - JSDoc comments with cURL examples
-- 🔄 **Custom Code Injection** - Preserve your custom code between regenerations
+### 🎉 v5.0.0 - Enhanced Client Generation & Developer Experience
+
+- 🚀 **Fully-Typed API Client Generation** - Generate type-safe clients for Fetch, Axios, React Query, SWR, and RTK Query with comprehensive inline documentation
+- ⚡ **RTK Query Simplified Setup** - New `setupApiStore` helper reduces Redux configuration from ~15 lines to ~5 lines
+- ✅ **Perfect TypeScript Support** - Fixed SWR mutation types, ESLint-compliant Fetch clients, and unique RTK Query reducer paths
+- 🎨 **Better File Organization** - Streamlined non-folder-split mode with `clients.ts` and `hooks.ts` directly at root
+- 🔧 **CLI Improvements** - Arguments now correctly override config file settings as expected
+- 📚 **230+ Lines of SWR Documentation** - Every generated hooks file includes comprehensive usage examples
+
+### Core Features
+
+- 🔄 **Real-time API Synchronization** - Automatically syncs OpenAPI specs from remote URLs with configurable intervals
+- 📝 **Automatic Type Generation** - Generates TypeScript interfaces for all endpoints with full nested support
+- 🔐 **Runtime Validation** - Generate Zod, Yup, or Joi schemas from OpenAPI specs with all constraints preserved
+- 🎯 **Interactive Setup Wizard** - Streamlined configuration with auto-enabled tag-based folder splitting
+- 🛡️ **Enterprise Ready** - Error handling, validation, state persistence, and custom code preservation
+- 📦 **Folder Splitting** - Organize code by tags or custom logic with aggregator files for easy imports
+- 📚 **Rich Documentation** - JSDoc comments with cURL examples and inline usage guides
+- 🔄 **Custom Code Injection** - Preserve your custom code between regenerations with protected sections
 
 [View all features →](https://openapi-sync.com/docs#features)
 
@@ -32,6 +44,28 @@ npx openapi-sync
 
 ## Quick Start
 
+### Option 1: Interactive Setup (Recommended) 🎯
+
+The easiest way to get started is with the interactive setup wizard:
+
+```bash
+npx openapi-sync init
+```
+
+The wizard will guide you through:
+
+- 📝 Configuration file format selection (TypeScript, JSON, or JavaScript)
+- 🌐 API specification source (URL or local file)
+- 📁 Folder organization options (split by tags or custom logic)
+- 🚀 Client generation options (React Query, SWR, Fetch, Axios, RTK Query)
+- ✅ Validation library setup (Zod, Yup, Joi)
+- 🔧 Custom code preservation settings
+- 🏷️ Type naming preferences (operationId usage, prefix)
+- 🚫 Endpoint filtering (exclude by tags)
+- 📚 Documentation options (cURL examples)
+
+### Option 2: Manual Setup
+
 **1. Create `openapi.sync.json` in your project root:**
 
 ```json
@@ -61,6 +95,139 @@ const petUrl = getPetById("123"); // Returns: "/pet/123"
 
 [View detailed quick start guide →](https://openapi-sync.com/docs#quick-start)
 
+## API Client Generation
+
+Generate fully-typed API clients with hooks for popular libraries:
+
+### Generate Fetch Client
+
+```bash
+npx openapi-sync generate-client --type fetch
+```
+
+### Generate Axios Client
+
+```bash
+npx openapi-sync generate-client --type axios
+```
+
+### Generate React Query Hooks
+
+```bash
+npx openapi-sync generate-client --type react-query --api petstore
+```
+
+### Generate SWR Hooks
+
+```bash
+npx openapi-sync generate-client --type swr
+```
+
+### Generate RTK Query API
+
+```bash
+npx openapi-sync generate-client --type rtk-query
+```
+
+### Filter by Tags or Endpoints
+
+```bash
+# Filter by tags
+npx openapi-sync generate-client --type fetch --tags pets,users
+
+# Filter by specific endpoints
+npx openapi-sync generate-client --type axios --endpoints getPetById,createPet
+```
+
+### Usage Example (React Query)
+
+**1. Generate the client:**
+
+```bash
+npx openapi-sync generate-client --type react-query
+```
+
+**2. Use in your React components:**
+
+```typescript
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useGetPetById, useCreatePet } from "./api/petstore/client/hooks";
+import apiClient from "./api/petstore/client/client";
+
+// Configure API client
+apiClient.updateConfig({
+  baseURL: "https://api.example.com",
+});
+apiClient.setAuthToken("your-auth-token");
+
+function PetDetails({ petId }: { petId: string }) {
+  // Query hook for GET requests with structured params
+  const { data, isLoading, error } = useGetPetById({
+    url: { petId }, // Path parameters
+    query: { includeOwner: true }, // Query parameters (if any)
+  });
+
+  // Mutation hook for POST/PUT/PATCH/DELETE requests
+  const createPet = useCreatePet({
+    onSuccess: () => {
+      console.log("Pet created!");
+    },
+  });
+
+  const handleCreate = () => {
+    createPet.mutate({
+      data: {
+        // Request body
+        name: "Fluffy",
+        species: "cat",
+      },
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>{data?.name}</h1>
+      <button onClick={handleCreate}>Create New Pet</button>
+    </div>
+  );
+}
+```
+
+### Client Generation Options
+
+| Option            | Description              | Example                                             |
+| ----------------- | ------------------------ | --------------------------------------------------- |
+| `--type, -t`      | Client type to generate  | `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`                |
+
+### Custom Code Preservation
+
+Generated clients support custom code sections that are preserved during regeneration:
+
+```typescript
+// client.ts (Generated)
+
+// ============================================================
+// 🔒 CUSTOM CODE START
+// Add your custom code below this line
+// This section will be preserved during regeneration
+// ============================================================
+
+// Your custom helper functions, middleware, etc.
+
+// 🔒 CUSTOM CODE END
+// ============================================================
+```
+
+[View complete client generation guide →](https://openapi-sync.com/docs#client-generation)
+
 ## Configuration
 
 Supports multiple configuration formats: `openapi.sync.json`, `openapi.sync.ts`, or `openapi.sync.js`
@@ -102,6 +269,56 @@ export default config;
 
 [View full configuration options →](https://openapi-sync.com/docs#configuration)
 
+## CLI Commands
+
+### Interactive Setup
+
+```bash
+npx openapi-sync init
+```
+
+Launch an interactive wizard that guides you through creating your configuration file. Perfect for first-time setup or exploring available options.
+
+### Sync API Types
+
+```bash
+# Sync with default config
+npx openapi-sync
+
+# Sync with custom refetch interval
+npx openapi-sync --refreshinterval 10000
+```
+
+Synchronize your OpenAPI specifications and generate TypeScript types, endpoints, and validation schemas.
+
+### Generate API Client
+
+```bash
+# Generate React Query hooks
+npx openapi-sync generate-client --type react-query
+
+# Generate for specific API
+npx openapi-sync generate-client --type axios --api petstore
+
+# Generate with filters
+npx openapi-sync generate-client --type fetch --tags pets,users
+
+# Generate for specific endpoints
+npx openapi-sync generate-client --type swr --endpoints getPetById,createPet
+```
+
+Generate fully-typed API clients for various frameworks and libraries.
+
+### Available Options
+
+| Command           | Description                           |
+| ----------------- | ------------------------------------- |
+| `init`            | Interactive setup wizard              |
+| `sync` (default)  | Sync OpenAPI specs and generate types |
+| `generate-client` | Generate API client code              |
+| `--help, -h`      | Show help information                 |
+| `--version, -v`   | Show version number                   |
+
 ## Documentation
 
 For complete documentation including:

package/bin/cli.js

@@ -5,17 +5,110 @@ const OpenApisync = require("../dist/index");
 const yargs = require("yargs/yargs");
 const { hideBin } = require("yargs/helpers");
 
-// Setup yargs
+// Setup yargs with commands
 const argv = yargs(hideBin(process.argv))
-  .usage("Usage: $0 [options]")
-  .option("refreshinterval", {
-    alias: "ri",
-    type: "number",
-    description: "Interval at which to refetch specifiations",
-  })
-  .help().argv;
+  .command(
+    "init",
+    "Interactive setup wizard to create configuration",
+    () => {},
+    async () => {
+      await OpenApisync.InteractiveInit();
+    }
+  )
+  .command(
+    ["$0", "sync"],
+    "Sync OpenAPI specifications and generate types",
+    (yargs) => {
+      return yargs.option("refreshinterval", {
+        alias: "ri",
+        type: "number",
+        description: "Interval at which to refetch specifications",
+      });
+    },
+    (argv) => {
+      OpenApisync.Init({
+        refetchInterval: argv.refreshinterval,
+      });
+    }
+  )
+  .command(
+    "generate-client",
+    "Generate API client from OpenAPI specification",
+    (yargs) => {
+      return yargs
+        .option("type", {
+          alias: "t",
+          type: "string",
+          description: "Client type to generate",
+          choices: ["fetch", "axios", "react-query", "swr", "rtk-query"],
+          demandOption: true,
+        })
+        .option("api", {
+          alias: "a",
+          type: "string",
+          description:
+            "API name from config (generates for all APIs if not specified)",
+        })
+        .option("tags", {
+          type: "array",
+          description: "Filter endpoints by tags",
+        })
+        .option("endpoints", {
+          alias: "e",
+          type: "array",
+          description: "Filter by specific endpoint names",
+        })
+        .option("output", {
+          alias: "o",
+          type: "string",
+          description: "Output directory for generated client",
+        })
+        .option("base-url", {
+          alias: "b",
+          type: "string",
+          description: "Base URL for API requests",
+        })
+        .example(
+          "$0 generate-client --type fetch",
+          "Generate fetch client for all APIs"
+        )
+        .example(
+          "$0 generate-client --type react-query --api petstore",
+          "Generate React Query hooks for petstore API"
+        )
+        .example(
+          "$0 generate-client --type axios --tags pets,users",
+          "Generate axios client for endpoints with pets or users tags"
+        )
+        .example(
+          "$0 generate-client --type swr --endpoints getPetById,createPet",
+          "Generate SWR hooks for specific endpoints"
+        );
+    },
+    async (argv) => {
+      // First, sync API specs and generate types/endpoints
+      console.log("🔄 Syncing API specifications first...\n");
+      await OpenApisync.Init();
 
-// Use the flags
-OpenApisync.Init({
-  refetchInterval: argv.refreshinterval,
-});
+      console.log("\n🚀 Now generating client...\n");
+
+      // Then generate the client
+      await OpenApisync.GenerateClient({
+        type: argv.type,
+        apiName: argv.api,
+        tags: argv.tags,
+        endpoints: argv.endpoints,
+        outputDir: argv.output,
+        baseURL: argv["base-url"],
+      });
+    }
+  )
+  .example("$0 init", "Start interactive setup wizard")
+  .example("$0", "Sync API types and endpoints")
+  .example("$0 --refreshinterval 10000", "Sync with 10s refresh interval")
+  .help()
+  .alias("help", "h")
+  .version()
+  .alias("version", "v")
+  .demandCommand(1, "You need to specify a command")
+  .strict().argv;

package/dist/chunk-PUWCZVB7.mjs

@@ -0,0 +1 @@
+var m=Object.defineProperty,n=Object.defineProperties;var o=Object.getOwnPropertyDescriptors;var h=Object.getOwnPropertySymbols;var p=Object.prototype.hasOwnProperty,q=Object.prototype.propertyIsEnumerable;var i=(b,c,a)=>c in b?m(b,c,{enumerable:true,configurable:true,writable:true,value:a}):b[c]=a,r=(b,c)=>{for(var a in c||(c={}))p.call(c,a)&&i(b,a,c[a]);if(h)for(var a of h(c))q.call(c,a)&&i(b,a,c[a]);return b},s=(b,c)=>n(b,o(c));var t=(b=>typeof require!="undefined"?require:typeof Proxy!="undefined"?new Proxy(b,{get:(c,a)=>(typeof require!="undefined"?require:c)[a]}):b)(function(b){if(typeof require!="undefined")return require.apply(this,arguments);throw Error('Dynamic require of "'+b+'" is not supported')});var u=(b,c,a)=>new Promise((j,g)=>{var k=d=>{try{e(a.next(d));}catch(f){g(f);}},l=d=>{try{e(a.throw(d));}catch(f){g(f);}},e=d=>d.done?j(d.value):Promise.resolve(d.value).then(k,l);e((a=a.apply(b,c)).next());});export{r as a,s as b,t as c,u as d};