auto-api-hooks 1.0.1 → 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]
@@ -1027,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-api-hooks",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Auto-generate type-safe React hooks from OpenAPI, Swagger, and GraphQL specs. Supports fetch, Axios, React Query, and SWR with optional Zod validation and MSW mock generation.",
   "license": "MIT",
   "type": "module",