swaggie 1.9.0 → 2.0.0

package/README.md

@@ -21,13 +21,15 @@ See the [Example section](#example) for a quick demo, or visit the full document
 ## Features
 
 - Generates TypeScript code from OpenAPI 3.0, 3.1, and 3.2 specs
-- Supports multiple HTTP client libraries out of the box: `fetch`, `axios`, `xior`, `SWR + axios`, `Angular 1`, `Angular 2+`, and `TanStack Query`
+- Supports multiple HTTP client libraries out of the box: `fetch`, `axios`, `xior`, `Angular 1`, `Angular 2+`; with optional reactive layers (`swr`, `tsq`) that compose with any compatible HTTP client
+- **Auto-generated mock/stub files** for Vitest and Jest — typed spies for every client method and hook, with ergonomic helpers like `mockSWR()` and `mockQuery()`
 - Custom templates — bring your own to fit your existing codebase
 - Supports `allOf`, `oneOf`, `anyOf`, `$ref`, nullable types, and various enum definitions
 - Handles multiple content types: JSON, plain text, multipart/form-data, URL-encoded, and binary
 - JSDoc comments on all generated functions
 - Generates a single, small, tree-shakable output file
 - Dev-only dependency — zero runtime overhead
+- Ability to generate automatic client mocks for `vitest` and `jest`
 
 ---
 
@@ -72,24 +74,27 @@ swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore
 **Available options:**
 
 ```
--V, --version              Output the version number
--c, --config <path>        Path to a JSON configuration file
--s, --src <url|path>       URL or file path to the OpenAPI spec
--o, --out <filePath>       Output file path (omit to print to stdout)
--b, --baseUrl <string>     Default base URL for the generated client (default: "")
--t, --template <string>    Template to use for code generation (default: "axios")
--m, --mode <mode>          Generation mode: "full" or "schemas" (default: "full")
--d, --schemaStyle <style>  Schema object style: "interface" or "type" (default: "interface")
-    --enumStyle <style>    Enum style for plain string enums: "union" or "enum" (default: "union")
-    --enumNamesStyle <s>   Enum member name casing: "original" or "PascalCase" (default: "original")
-    --dateFormat <format>  Date handling in schemas: "Date" or "string"
-    --nullables <strategy> Nullable handling: "include", "nullableAsOptional", or "ignore"
-    --preferAny            Use "any" instead of "unknown" for untyped values (default: false)
-    --skipDeprecated       Exclude deprecated operations from the output (default: false)
-    --servicePrefix        Prefix for service names — useful when generating multiple APIs
-    --allowDots            Use dot notation to serialize nested object query params
-    --arrayFormat          How arrays are serialized: "indices", "repeat", or "brackets"
--h, --help                 Show help
+-V, --version                  Output the version number
+-c, --config <path>            Path to a JSON configuration file
+-s, --src <url|path>           URL or file path to the OpenAPI spec
+-o, --out <filePath>           Output file path (omit to print to stdout)
+-b, --baseUrl <string>         Base URL that will be used as a default value in the clients
+-t, --template <string>        Template to use. Single name: "axios", "fetch", "xior", "ng1", "ng2", "swr", "tsq". Reactive pair: "swr,axios" / "tsq,xior" / etc. (default: "axios")
+-m, --mode <mode>              Generation mode: "full" or "schemas" (default: "full")
+-d, --schemaStyle <style>      Schema object style: "interface" or "type" (default: "interface")
+    --enumStyle <style>        Enum style for plain string enums: "union" or "enum" (default: "union")
+    --enumNamesStyle <s>       Enum member name casing: "original" or "PascalCase" (default: "original")
+    --dateFormat <format>      How date fields are emitted in generated types
+    --nullables <strategy>     Nullable handling: "include", "nullableAsOptional", or "ignore"
+    --preferAny                Use "any" instead of "unknown" for untyped values (default: false)
+    --skipDeprecated           Exclude deprecated operations from the output (default: false)
+    --servicePrefix            Prefix for service names — useful when generating multiple APIs
+    --allowDots                Use dot notation to serialize nested object query params
+    --arrayFormat              How arrays are serialized: "indices", "repeat", or "brackets"
+-C, --useClient                Prepend 'use client'; directive (Next.js App Router + SWR/TSQ)
+    --mocks <path>             Output path for a generated mock/stub file (requires --testingFramework and --out)
+-T, --testingFramework <name>  Framework for generated mocks: "vitest" or "jest" (requires --mocks and --out)
+-h, --help                     Show help
 ```
 
 ### Formatting the Output
@@ -142,24 +147,72 @@ The `$schema` field enables autocompletion and inline documentation in most edit
 
 ## Templates
 
-Swaggie ships with the following built-in templates:
+Swaggie's templates are split into two independent layers that you can combine freely.
 
-| Template    | Description                                                                               |
-| ----------- | ----------------------------------------------------------------------------------------- |
-| `axios`     | Default. Recommended for React, Vue, and similar frameworks                               |
-| `xior`      | Lightweight modern alternative to axios ([xior](https://github.com/suhaotian/xior#intro)) |
-| `swr-axios` | SWR hooks for GET requests, backed by axios                                               |
-| `tsq-xior`  | TanStack Query hooks for GET requests, backed by xior                                     |
-| `fetch`     | Uses the native browser Fetch API                                                         |
-| `ng1`       | Angular 1 client                                                                          |
-| `ng2`       | Angular 2+ client (uses HttpClient and InjectionTokens)                                   |
+### HTTP client templates
 
-To use a custom template, pass the path to your template directory:
+These are standalone and cover the most common client libraries:
+
+| Template | Description |
+| -------- | ----------- |
+| `axios`  | Default. Recommended for React, Vue, and most Node.js projects |
+| `fetch`  | Native browser/Node 18+ Fetch API — zero runtime dependencies |
+| `xior`   | Lightweight Axios-compatible alternative ([xior](https://github.com/suhaotian/xior#intro)) |
+| `ng1`    | Angular 1 client |
+| `ng2`    | Angular 2+ client (uses `HttpClient` and `InjectionToken`) |
+
+### Reactive query layer templates
+
+These add a reactive data-fetching layer (SWR or TanStack Query hooks) on top of any compatible http client. They cannot be used alone — pair them with a basic template using a 2-element array:
+
+| Template | Description |
+| -------- | ----------- |
+| `swr`    | [SWR](https://swr.vercel.app) hooks for queries and mutations |
+| `tsq`    | [TanStack Query](https://tanstack.com/query) hooks for queries and mutations |
+
+Compatible http client templates: `axios`, `fetch`, `xior`. Angular clients are not compatible with reactive layers.
+
+### Usage examples
+
+**Single http template (existing behaviour):**
+
+```json
+{ "template": "axios" }
+```
+
+```bash
+swaggie -s ./openapi.json -o ./client.ts -t axios
+```
+
+**Pair combination — in config:**
+
+```json
+{ "template": ["swr", "axios"] }
+```
+
+```bash
+# CLI: comma-separated pair
+swaggie -s ./openapi.json -o ./client.ts -t swr,axios
+swaggie -s ./openapi.json -o ./client.ts -t tsq,xior
+swaggie -s ./openapi.json -o ./client.ts -t swr,fetch
+```
+
+**Reactive template only — defaults to `fetch` as the http client:**
+
+```json
+{ "template": "swr" }
+```
+
+### Custom templates
+
+Pass the path to your own template directory as the template value:
 
 ```bash
 swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore.ts --template ./my-swaggie-template/
 ```
 
+Custom paths also work as part of a composite pair: `["./my-l2", "axios"]`.
+
 ---
 
 ## Example
@@ -179,7 +232,7 @@ import Axios, { AxiosPromise } from 'axios';
 
 const axios = Axios.create({
   baseURL: '/api',
-  paramsSerializer: (params) =>
+  paramsSerializer: (params: any) =>
     encodeParams(params, null, {
       allowDots: true,
       arrayFormat: 'repeat',
@@ -359,6 +412,39 @@ Either tool needs to be installed separately and configured for your project.
 
 ---
 
+## Generating Mocks
+
+Swaggie can generate a companion mock file alongside your client — a set of typed spy stubs for every method and hook, ready to drop into your tests.
+
+```bash
+swaggie -s ./spec.json -o ./src/api/client.ts -t swr,axios \
+  --mocks ./src/__mocks__/api.ts --testingFramework vitest
+```
+
+Or in a config file:
+
+```json
+{
+  "src": "./openapi.json",
+  "out": "./src/api/client.ts",
+  "template": ["swr", "axios"],
+  "mocks": "./src/__mocks__/api.ts",
+  "testingFramework": "vitest"
+}
+```
+
+The generated mock file exports the same names as the real client, so `vi.mock('./api', () => import('./__mocks__/api'))` is all you need in tests. For (SWR/TSQ) templates, hook stubs come with shorthand helpers:
+
+```ts
+pet.queries.usePetById.mockSWR({ data: { id: 1, name: 'Rex' } });
+pet.mutations.useAddPet.mockSWRMutation({ isMutating: false });
+// TanStack Query equivalents: mockQuery() / mockMutation()
+```
+
+See the [Mocking guide](https://yhnavein.github.io/swaggie/guide/mocking) for full details.
+
+---
+
 ## Using Swaggie Programmatically
 
 You can also call Swaggie directly from Node.js/bun/deno/etc:

package/dist/browser.js

@@ -9,6 +9,8 @@ var _bundledTemplates = require('./generated/bundledTemplates');
 var _utils = require('./utils/utils');
 var _documentLoaderbrowser = require('./utils/documentLoader.browser');
 var _templateEngine = require('./utils/templateEngine');
+var _templateValidator = require('./utils/templateValidator');
+var _templateManager = require('./utils/templateManager');
 
 /**
  * Browser-friendly code generation entrypoint.
@@ -52,12 +54,27 @@ async function generateCode(spec, options) {
     return _header.FILE_HEADER + _genTypes2.default.call(void 0, spec, options, false);
   }
 
-  const templateFiles = _bundledTemplates.BUNDLED_TEMPLATES[options.template];
-  if (!templateFiles) {
-    throw new Error(`Bundled templates for '${options.template}' are not available`);
+  _templateValidator.validateTemplate.call(void 0, options.template);
+
+  if (Array.isArray(options.template)) {
+    const [l2, l1] = options.template;
+    const l1Files = _bundledTemplates.BUNDLED_TEMPLATES[l1 ];
+    const l2Files = _bundledTemplates.BUNDLED_TEMPLATES[l2 ];
+    if (!l1Files) {
+      throw new Error(`Bundled templates for L1 '${l1}' are not available`);
+    }
+    if (!l2Files) {
+      throw new Error(`Bundled templates for L2 '${l2}' are not available`);
+    }
+    _templateEngine.initTemplateEngineFromBundled.call(void 0, _templateManager.mergeTemplateFiles.call(void 0, l1Files, l2Files));
+  } else {
+    const templateFiles = _bundledTemplates.BUNDLED_TEMPLATES[options.template ];
+    if (!templateFiles) {
+      throw new Error(`Bundled templates for '${options.template}' are not available`);
+    }
+    _templateEngine.initTemplateEngineFromBundled.call(void 0, templateFiles);
   }
 
-  _templateEngine.initTemplateEngineFromBundled.call(void 0, templateFiles);
   const operationsCode = await _genOperations2.default.call(void 0, spec, options);
 
   return operationsCode + _genTypes2.default.call(void 0, spec, options);
@@ -70,6 +87,7 @@ async function generateCode(spec, options) {
   const {
     allowDots,
     arrayFormat,
+    queryParamsAsObject,
     mode,
     schemaStyle,
     enumStyle,
@@ -86,11 +104,12 @@ async function generateCode(spec, options) {
     ),
     ...(allowDots !== undefined ? { allowDots } : {}),
     ...(arrayFormat !== undefined ? { arrayFormat } : {}),
+    ...(queryParamsAsObject !== undefined ? { queryParamsAsObject } : {}),
   };
 
   return {
     ...rest,
-    template: _nullishCoalesce(template, () => ( _swagger.APP_DEFAULTS.template)),
+    template: _templateValidator.normalizeTemplate.call(void 0, _nullishCoalesce(template, () => ( _swagger.APP_DEFAULTS.template))),
     servicePrefix: _nullishCoalesce(rest.servicePrefix, () => ( _swagger.APP_DEFAULTS.servicePrefix)),
     nullableStrategy: _nullishCoalesce(_nullishCoalesce(nullables, () => ( rest.nullableStrategy)), () => ( _swagger.APP_DEFAULTS.nullableStrategy)),
     generationMode: _nullishCoalesce(_nullishCoalesce(mode, () => ( rest.generationMode)), () => ( _swagger.APP_DEFAULTS.generationMode)),

package/dist/cli.js

@@ -13,12 +13,14 @@ const arrayFormatOption = new (0, _commander.Option)(
   'Determines how arrays should be serialized'
 ).choices(['indices', 'repeat', 'brackets']);
 
+const testingFrameworkOption = new (0, _commander.Option)(
+  '-T, --testingFramework <framework>',
+  'Test framework for generated mock stubs (requires --mocks and --out)'
+).choices(['vitest', 'jest']);
+
 const packageJson = readPackageJson();
 
-const modeOption = new (0, _commander.Option)('-m, --mode <mode>', 'Generation mode').choices([
-  'full',
-  'schemas',
-]);
+const modeOption = new (0, _commander.Option)('-m, --mode <mode>', 'Generation mode').choices(['full', 'schemas']);
 const schemaStyleOption = new (0, _commander.Option)(
   '-d, --schemaStyle <style>',
   'Schema object declaration style'
@@ -39,6 +41,10 @@ const nullableStrategyOption = new (0, _commander.Option)(
   '--nullables <strategy>',
   "Controls how OpenAPI 'nullable' is translated into TypeScript types"
 ).choices(['include', 'nullableAsOptional', 'ignore']);
+const queryParamsAsObjectOption = new (0, _commander.Option)(
+  '--queryParamsAsObject [threshold]',
+  'Group query params into a single object; pass a number to group only when query params count is greater than threshold'
+).argParser(parseQueryParamsAsObjectArg);
 
 const program = new (0, _commander.Command)();
 program
@@ -63,9 +69,18 @@ program
   .option('-b, --baseUrl <string>', 'Base URL that will be used as a default value in the clients')
   .option(
     '-t, --template <string>',
-    'Template used for generating API client. Default: "axios". Other: "fetch", "ng1", "ng2", "swr-axios", "xior", "tsq-xior"'
+    'Template used for generating API client. ' +
+      'L1 (HTTP client) templates: "axios" (default), "fetch", "xior", "ng1", "ng2". ' +
+      'L2 (reactive layer) templates must be paired with an L1 using a comma-separated value: ' +
+      '"swr,axios", "swr,fetch", "tsq,xior", "tsq,fetch", etc. ' +
+      'Providing only an L2 name (e.g. "swr") defaults to "fetch" as the L1.',
+    parseTemplateArg
   )
   .option('--preferAny', 'Use "any" type instead of "unknown"')
+  .option(
+    '-C, --useClient',
+    "Prepend 'use client'; to the generated file. Required for Next.js App Router with SWR or TanStack Query hooks"
+  )
   .option(
     '--skipDeprecated',
     'Skip deprecated operations. When enabled, deprecated operations will be skipped from the generated code'
@@ -84,13 +99,19 @@ program
   .addOption(enumStyleOption)
   .addOption(enumNamesStyleOption)
   .addOption(dateFormatOption)
-  .addOption(nullableStrategyOption);
+  .addOption(nullableStrategyOption)
+  .addOption(queryParamsAsObjectOption)
+  .option(
+    '--mocks <path>',
+    'Output path for the generated mock/stub file (requires --testingFramework and --out)'
+  )
+  .addOption(testingFrameworkOption);
 
 program.parse(process.argv);
 
 const options = program.opts();
 
-_index.runCodeGenerator.call(void 0, options).then(complete, error);
+_index.runCodeGenerator.call(void 0, options ).then(complete, error);
 
 function complete([code, opts]) {
   if (opts.out) {
@@ -116,3 +137,29 @@ function readPackageJson() {
     throw new Error('Could not read package.json file');
   }
 }
+
+function parseTemplateArg(value) {
+  const parts = value.split(',').map((s) => s.trim());
+  if (parts.length === 1) {
+    return parts[0];
+  }
+  if (parts.length === 2) {
+    return [parts[0], parts[1]];
+  }
+  throw new Error(
+    `--template accepts at most 2 comma-separated values (e.g. "swr,axios"). Got ${parts.length}.`
+  );
+}
+
+function parseQueryParamsAsObjectArg(value) {
+  if (value === undefined) {
+    return true;
+  }
+
+  const threshold = Number(value);
+  if (!Number.isInteger(threshold) || threshold < 0) {
+    throw new Error('--queryParamsAsObject threshold must be a non-negative integer');
+  }
+
+  return threshold;
+}