auto-api-hooks 1.0.0 → 1.0.2

package/README.md

@@ -1,21 +1,34 @@
-# auto-api-hooks
+# React Hooks Generator from OpenAPI, Swagger & GraphQL | auto-api-hooks
 
-Auto-generate type-safe React hooks from API specifications.
+Generate React Query hooks from OpenAPI specs. Generate SWR hooks from Swagger. Generate type-safe TypeScript API hooks from GraphQL schemas. One command, fully typed, tree-shakeable output with optional Zod schemas and MSW v2 mocks.
 
-`auto-api-hooks` reads your OpenAPI 3.x, Swagger 2.0, or GraphQL schema and produces ready-to-use React hooks, TypeScript types, optional Zod validation schemas, and MSW v2 mock handlers -- all from a single command.
+> `auto-api-hooks` -- the OpenAPI to React hooks generator that also supports Swagger 2.0 and GraphQL. Produces TanStack React Query v5 hooks, SWR hooks, or plain fetch hooks with zero config.
+
+`auto-api-hooks` is an API client generator and code generation tool that reads any OpenAPI 3.x, Swagger 2.0, or GraphQL schema and produces ready-to-use React hooks, TypeScript types, Zod validation schemas, and MSW v2 mock handlers -- all from a single `npx` command or programmatic API call.
+
+## Why Use an OpenAPI to React Hooks Generator?
+
+Maintaining hand-written fetch logic, TypeScript interfaces, and data-fetching hooks across dozens of API endpoints doesn't scale. Every backend change means manually updating types, adjusting error handling, and keeping request/response shapes in sync -- across every component that calls the API. Most OpenAPI code generation tools stop at a raw API client, leaving you to wire up React Query, SWR, or custom hooks yourself. `auto-api-hooks` generates idiomatic React hooks directly: `useQuery` for reads, `useMutation` for writes, `useInfiniteQuery` for paginated endpoints -- with full TypeScript types, optional Zod runtime validation, and MSW v2 mock servers.
+
+**Compared to alternatives:**
+
+- **vs orval** -- supports GraphQL schemas in addition to OpenAPI/Swagger, generates MSW v2 handlers (not v1) out of the box
+- **vs openapi-codegen** -- single `npx` command with no config file required; programmatic API for CI/CD integration included
+- **vs swagger-typescript-api** -- produces React hooks directly (React Query v5, SWR, or plain fetch) rather than a raw API client, with built-in pagination detection and infinite query generation
+- **vs openapi-typescript-codegen** -- generates Zod validation schemas from OpenAPI with format-aware refinements and watch mode for development workflows
 
 ## Features
 
-- **Multi-spec support** -- Generate React hooks from OpenAPI 3.x, Swagger 2.0, and GraphQL schemas
-- **Multiple fetcher strategies** -- Plain `fetch`, Axios, TanStack React Query v5, and SWR
-- **Optional Zod validation** -- Generate Zod schemas with format-aware refinements for runtime response validation
-- **Smart pagination detection** -- Automatically detects cursor-based, offset-limit, and page-number pagination patterns and generates infinite query hooks
-- **MSW v2 mock server generation** -- Produce request handlers, mock data factories, and server/browser setup files
+- **OpenAPI to TypeScript React hooks** -- Generate React hooks from OpenAPI 3.x, Swagger 2.0, and GraphQL schemas
+- **Generate React Query hooks from OpenAPI** -- TanStack React Query v5, SWR, Axios, or plain `fetch`
+- **Generate Zod schemas from OpenAPI** -- Format-aware refinements (`email`, `uuid`, `date-time`) for runtime response validation
+- **Auto-detect pagination, generate infinite query hooks** -- Cursor-based, offset-limit, and page-number patterns detected automatically
+- **Generate MSW v2 mock server from API spec** -- Request handlers, mock data factories, and server/browser setup files
 - **CLI tool + programmatic API** -- Use from the terminal or import `generate()` in your build scripts
 - **Watch mode** -- File-watching with debounced regeneration for development workflows
-- **TypeScript-first** -- Fully typed output with per-operation params, body, and response types
+- **Fully typed TypeScript output** -- Per-operation params, body, and response types emitted as interfaces
 - **One hook per file** -- Maximum tree-shakeability; bundlers only include what you import
-- **Cache key factories** -- React Query key factories following TanStack v5 best practices
+- **React Query cache key factories** -- Following TanStack v5 best practices
 
 ## Quick Start
 
@@ -25,7 +38,7 @@ Install the package:
 npm install auto-api-hooks
 ```
 
-Generate hooks from your API specification:
+Generate React hooks from your OpenAPI specification:
 
 ```bash
 npx auto-api-hooks generate --spec ./openapi.yaml --fetcher react-query --output ./src/hooks
@@ -58,7 +71,7 @@ function UserList() {
 }
 ```
 
-## CLI Usage
+## CLI Usage -- Generate React Hooks from OpenAPI, Swagger, or GraphQL
 
 ```
 auto-api-hooks generate [options]
@@ -564,7 +577,7 @@ await generate({
 
 Full support for OpenAPI 3.0 and 3.1 specifications, including:
 
-- `$ref` resolution across the document
+- `$ref` resolution across the document, including multi-file specs with external `$ref` paths (e.g. `$ref: './paths/users.yaml'`)
 - `components.schemas` mapped to TypeScript types and optional Zod schemas
 - `servers[0].url` used as the default base URL
 - All HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
@@ -575,7 +588,7 @@ Full support for OpenAPI 3.0 and 3.1 specifications, including:
 - Tag-based grouping of generated hooks
 - `x-pagination` vendor extension for explicit pagination hints
 
-**Supported file formats:** `.yaml`, `.yml`, `.json`
+**Supported file formats:** `.yaml`, `.yml`, `.json` (single-file or multi-file with relative `$ref` references)
 
 ### Swagger 2.0
 
@@ -584,8 +597,9 @@ Full support for Swagger 2.0 specifications, including:
 - `definitions` mapped to TypeScript types
 - `host` + `basePath` combined into the base URL
 - All standard Swagger features (parameters, responses, tags)
+- Multi-file specs with external `$ref` paths
 
-**Supported file formats:** `.yaml`, `.yml`, `.json`
+**Supported file formats:** `.yaml`, `.yml`, `.json` (single-file or multi-file with relative `$ref` references)
 
 ### GraphQL
 
@@ -1026,6 +1040,32 @@ test('renders todo list from mock data', async () => {
 
 If the backend returns data that does not match the schema, the Zod `.parse()` call inside the hook throws a `ZodError` with a detailed path to the invalid field. This surfaces API contract violations immediately during development rather than silently producing incorrect UI state.
 
+## FAQ
+
+**Does auto-api-hooks support OpenAPI 3.1?**
+Yes. Both OpenAPI 3.0 and 3.1 are fully supported, including multi-file specs with external `$ref` references.
+
+**Can I use it with Swagger 2.0?**
+Yes. Swagger 2.0 YAML and JSON files are supported alongside OpenAPI 3.x and GraphQL SDL/introspection.
+
+**Which React data-fetching libraries does it support?**
+Plain `fetch` (no extra dependencies), Axios, TanStack React Query v5, and SWR. Each generates idiomatic hooks for that library.
+
+**Does it generate TypeScript types automatically?**
+Yes. Every generated hook is fully typed -- path params, query params, request body, and response types are all emitted as TypeScript interfaces.
+
+**Can I generate Zod schemas from my OpenAPI spec?**
+Yes. Pass `--zod` to generate a `schemas.ts` file with Zod schemas for every named type and operation response, including format-aware refinements (`email`, `uuid`, `date-time`, `uri`).
+
+**Does it generate MSW mocks?**
+Yes. Pass `--mock` to generate a complete MSW v2 mock server with request handlers, data factories, and `setupServer`/`setupWorker` setup files.
+
+**How is this different from orval or openapi-typescript-codegen?**
+`auto-api-hooks` uniquely combines OpenAPI, Swagger, and GraphQL support in one tool, generates MSW v2 handlers (not v1), produces one hook per file for maximum tree-shakeability, and includes smart pagination detection with automatic infinite query hook generation.
+
+**Can I use it programmatically in a build script?**
+Yes. Import `generate()` directly from `auto-api-hooks` and pass a parsed spec object or file path. It returns generated file contents in memory when `outputDir` is omitted.
+
 ## Support
 
 If you find this package useful, consider buying me a coffee!

package/dist/cli.js

@@ -454,7 +454,7 @@ var openApiParser = {
   },
   async parse(input, options) {
     const derefed = await SwaggerParser.dereference(
-      input,
+      options?.filePath ?? input,
       { dereference: { circular: "ignore" } }
     );
     const doc = derefed;
@@ -789,7 +789,7 @@ var swaggerParser = {
   },
   async parse(input, options) {
     const derefed = await SwaggerParser.dereference(
-      input,
+      options?.filePath ?? input,
       { dereference: { circular: "ignore" } }
     );
     const doc = derefed;
@@ -1215,9 +1215,14 @@ async function parseSpec(input, options) {
   } else {
     resolved = input;
   }
+  const resolvedOptions = { ...options };
+  if (typeof input === "string" && /\.[a-z]{2,10}$/i.test(input) && !input.includes("\n")) {
+    const { resolve } = await import('path');
+    resolvedOptions.filePath = resolve(input);
+  }
   for (const parser of parsers) {
     if (parser.canParse(resolved)) {
-      const spec = await parser.parse(resolved, options);
+      const spec = await parser.parse(resolved, resolvedOptions);
       return applyPaginationDetection(spec);
     }
   }