auto-api-hooks 1.0.1 → 1.0.3

package/README.md

@@ -1,21 +1,40 @@
-# auto-api-hooks
+# React Hooks Generator from OpenAPI, Swagger & GraphQL | auto-api-hooks
 
-Auto-generate type-safe React hooks from API specifications.
+[![npm version](https://img.shields.io/npm/v/auto-api-hooks)](https://www.npmjs.com/package/auto-api-hooks)
+[![npm downloads](https://img.shields.io/npm/dm/auto-api-hooks)](https://www.npmjs.com/package/auto-api-hooks)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/auto-api-hooks)](https://bundlephobia.com/package/auto-api-hooks)
+[![license](https://img.shields.io/npm/l/auto-api-hooks)](https://github.com/abdallaemadeldin/auto-api-hooks/blob/master/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 
-`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.
+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` -- 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 +44,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 +77,7 @@ function UserList() {
 }
 ```
 
-## CLI Usage
+## CLI Usage -- Generate React Hooks from OpenAPI, Swagger, or GraphQL
 
 ```
 auto-api-hooks generate [options]
@@ -1027,6 +1046,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,8 +1,17 @@
 {
   "name": "auto-api-hooks",
-  "version": "1.0.1",
-  "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.",
+  "version": "1.0.3",
+  "description": "Generate React Query hooks, SWR hooks, and TypeScript types from OpenAPI 3.x, Swagger 2.0, and GraphQL specs. API client code generator with Zod schema validation and MSW v2 mock server generation.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abdallaemadeldin/auto-api-hooks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abdallaemadeldin/auto-api-hooks/issues"
+  },
+  "homepage": "https://github.com/abdallaemadeldin/auto-api-hooks#readme",
+  "author": "Abdalla Emad Eldin",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -71,4 +80,4 @@
     "api-client",
     "hooks-generator"
   ]
-}
+}