Configuration

For anything beyond a one-off run, a configuration file is the cleaner approach. It keeps all your settings version-controlled alongside your code and makes regeneration a single command.

Creating a config file

Create a JSON file (conventionally named swaggie.config.json) at the root of your project:

{
  "$schema": "https://raw.githubusercontent.com/yhnavein/swaggie/master/schema.json",
  "src": "https://petstore3.swagger.io/api/v3/openapi.json",
  "out": "./src/api/petstore.ts",
  "template": "axios",
  "baseUrl": "/api",
  "preferAny": false,
  "skipDeprecated": false,
  "servicePrefix": "",
  "dateFormat": "Date",
  "nullableStrategy": "ignore",
  "generationMode": "full",
  "schemaDeclarationStyle": "interface",
  "enumDeclarationStyle": "union",
  "enumNamesStyle": "original",
  "queryParamsSerialization": {
    "arrayFormat": "repeat",
    "allowDots": true
  }
}

Then run:

swaggie -c swaggie.config.json

Editor autocompletion

The $schema field enables full autocompletion and inline documentation in VS Code, WebStorm, and any other editor that supports JSON Schema. You'll see descriptions and valid values for every option as you type.

All configuration options

src required

Type: string

URL or local file path to the OpenAPI spec. Accepts .json and .yaml files.

{ "src": "https://api.example.com/openapi.json" }
{ "src": "./specs/openapi.yaml" }

---

out required

Type: string

Output file path for the generated TypeScript client. Omit when using the programmatic API if you want the code returned as a string.

{ "out": "./src/api/client.ts" }

---

template

Type: string | [string, string]   Default: "axios"

The template to use for code generation. Accepts:

• A single HTTP client template name: "axios", "fetch", "xior", "ng1", "ng2"
• A single reactive layer template name (defaults to fetch as the HTTP client): "swr", "tsq"
• A 2-element array pairing a reactive layer with an HTTP client: ["swr", "axios"], ["tsq", "xior"], etc.
• A path to a custom template directory

See Templates for a full comparison and valid combinations.

{ "template": "fetch" }

---

baseUrl

Type: string   Default: ""

The default base URL baked into the generated client. Useful when your API is always at a known path prefix (e.g., /api).

{ "baseUrl": "/api/v1" }

---

generationMode

Type: "full" | "schemas"   Default: "full"

Controls what gets generated:

Value	Output
"full"	Client methods + all referenced TypeScript schemas
"schemas"	Only TypeScript schemas — all components/schemas entries, no client methods

Use "schemas" when you only need types (e.g., for form validation or server-side code).

---

schemaDeclarationStyle

Type: "interface" | "type"   Default: "interface"

How object schemas are declared in the output:

// "interface" (default)
export interface Pet { id?: number; name: string; }

// "type"
export type Pet = { id?: number; name: string; };

---

enumDeclarationStyle

Type: "union" | "enum"   Default: "union"

How plain string enums are declared:

// "union" (default)
export type Status = 'available' | 'pending' | 'sold';

// "enum"
export enum Status { available = 'available', pending = 'pending', sold = 'sold' }

INFO

Non-string enums (numeric, mixed) are always emitted as union types regardless of this setting.

---

enumNamesStyle

Type: "original" | "PascalCase"   Default: "original"

Controls how enum member names are formatted when generating TypeScript enum declarations. Only takes effect when enumDeclarationStyle is set to "enum".

// "original" (default) — member names match the raw enum values
export enum Status { active = 'active', 'not active' = 'not active' }

// "PascalCase" — member names are converted to PascalCase
export enum Status { Active = 'active', NotActive = 'not active' }

The enum values are never modified — only the member names are transformed. This is useful when you want clean, idiomatic TypeScript identifiers for your enum members without changing the wire format.

TIP

The CLI accepts both --enumNamesStyle PascalCase and --enumNamesStyle pascal as equivalent values.

---

nullableStrategy

Type: "ignore" | "include" | "nullableAsOptional"   Default: "ignore"

How nullable: true fields in the spec are handled. See Nullable Strategy for a detailed explanation.

---

dateFormat

Type: "Date" | "string"   Default: "Date"

Controls the TypeScript type used for format: date and format: date-time schema fields.

// "Date" (default)
createdAt: Date;

// "string"
createdAt: string;

---

preferAny

Type: boolean   Default: false

When true, uses any instead of unknown for untyped / free-form values. Useful when migrating a large codebase where unknown would require too many type guards.

---

skipDeprecated

Type: boolean   Default: false

When true, operations marked deprecated: true in the spec are excluded from the generated output.

---

useClient

Type: boolean   Default: false

When true, prepends 'use client'; as the very first line of the generated file. Required for Next.js App Router when using swr or tsq templates, which produce React hooks that can only run inside Client Components.

{ "useClient": true }

Has no effect and should not be used outside of Next.js App Router (RSC) environments.

---

servicePrefix

Type: string   Default: ""

A string prepended to every generated service (client object) name. Useful when generating clients for multiple APIs to avoid naming collisions.

{ "servicePrefix": "Petstore" }

This would turn petClient into PetstorePetClient.

---

queryParamsSerialization

Type: object

Controls how query parameters are serialized. The defaults match what ASP.NET Core expects.

{
  "queryParamsSerialization": {
    "allowDots": true,
    "arrayFormat": "repeat"
  }
}

Property	Type	Default	Description
allowDots	boolean	true	Use dot notation for nested objects (a.b=1 instead of a[b]=1)
arrayFormat	"repeat" | "brackets" | "indices"	"repeat"	How arrays are serialized in the query string
queryParamsAsObject	boolean | number	—	Group all query parameters into a single typed object argument. true always groups; a number N groups only when there are more than N query params

See Query Parameter Serialization and Query Parameter Grouping for full details.

---

mocks

Type: string

Output path for the generated mock/stub file. When set, Swaggie writes a companion file exporting typed spy stubs for every client method and hook. Requires testingFramework and out to also be set.

{ "mocks": "./src/__mocks__/api.ts" }

See Mocking for a full guide.

---

testingFramework

Type: "vitest" | "jest"

The test framework whose spy functions (vi.fn() or jest.fn()) are used in the generated mock file. Requires mocks and out to also be set.

{ "testingFramework": "vitest" }

---

modifiers

Type: object

Override the required/optional/ignored status of specific parameters globally, without modifying the spec.

{
  "modifiers": {
    "parameters": {
      "clientId": "ignore",
      "orgId": "optional",
      "country": "required"
    }
  }
}

Value	Effect
"ignore"	Parameter is removed from all generated method signatures
"optional"	Parameter is always optional regardless of what the spec says
"required"	Parameter is always required

See Parameter Modifiers for more detail.