schema.json

{
  "$id": "https://github.com/yhnavein/swaggie/blob/master/schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Swaggie Settings Schema",
  "definitions": {
    "QueryParamsSerialization": {
      "additionalProperties": true,
      "description": "Settings for query parameters serialization",
      "properties": {
        "allowDots": {
          "description": "Determines if dots should be used for serialization object properties. Otherwise brackets will be used",
          "type": "boolean",
          "default": true
        },
        "arrayFormat": {
          "description": "Determines how arrays should be serialized",
          "enum": ["indices", "repeat", "brackets"],
          "type": "string",
          "default": "repeat"
        },
        "queryParamsAsObject": {
          "description": "Group all query parameters into a single object argument. Pass `true` to always group, or a positive integer N to group only when there are more than N query parameters.",
          "oneOf": [{ "type": "boolean" }, { "type": "integer", "minimum": 0 }],
          "default": false
        }
      }
    },
    "ExcludeOptions": {
      "additionalProperties": false,
      "description": "Excludes specific operations from code generation by tag or operationId. Supports * (any sequence of characters) and ? (any single character) wildcard patterns.",
      "properties": {
        "tags": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Exclude operations whose first tag matches any of these values. Supports * and ? wildcards."
        },
        "operationIds": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Exclude operations whose operationId matches any of these values. Supports * and ? wildcards."
        }
      }
    },
    "GlobalModifiers": {
      "additionalProperties": false,
      "description": "Global modifiers for parameters. It gives flexibility to adjust the OpenAPI spec before it is processed",
      "properties": {
        "parameters": {
          "type": "object",
          "description": "Global-level modifiers for parameters with a matching name",
          "additionalProperties": {
            "type": "string",
            "enum": ["optional", "required", "ignore"],
            "description": "Modify the parameter in the following way: `optional` - make the parameter optional, `required` - make the parameter required, `ignore` - remove the parameter from the operations"
          }
        }
      }
    },
    "GlobalsDefaults": {
      "additionalProperties": true,
      "description": "Shared settings that can be used as top-level defaults in a multi-config file or directly in a single-config file. The keys 'src', 'out', 'hooksOut', 'mocks', and 'clientSetup' are not part of this definition — they belong either in a single-config root (via Globals) or inside each entry under 'configs'.",
      "type": "object",
      "properties": {
        "template": {
          "default": "axios",
          "description": "Template that will be used for generating the API client. Use a single L1 template name (e.g. \"axios\"), a single L2 name (defaults to \"fetch\" as L1), or a [L2, L1] array for custom pairings.",
          "oneOf": [
            {
              "type": "string",
              "examples": ["axios", "fetch", "xior", "ky", "ng1", "ng2", "swr", "tsq"]
            },
            {
              "type": "array",
              "items": { "type": "string" },
              "minItems": 2,
              "maxItems": 2,
              "examples": [
                ["swr", "axios"],
                ["swr", "fetch"],
                ["swr", "xior"],
                ["swr", "ky"],
                ["tsq", "axios"],
                ["tsq", "fetch"],
                ["tsq", "xior"],
                ["tsq", "ky"]
              ]
            }
          ]
        },
        "baseUrl": {
          "default": "",
          "description": "Base URL that will be used as a default value in the clients",
          "type": "string"
        },
        "preferAny": {
          "default": false,
          "description": "Use `any` type instead of `unknown`",
          "type": "boolean"
        },
        "servicePrefix": {
          "default": "",
          "description": "Prefix for service names. Useful when you have multiple APIs and you want to avoid name collisions",
          "type": "string"
        },
        "skipDeprecated": {
          "default": false,
          "description": "Skip deprecated operations. When enabled, deprecated operations will be skipped from the generated code",
          "type": "boolean"
        },
        "useClient": {
          "default": false,
          "description": "Prepend 'use client'; as the very first line of the generated hooks file (when hooksOut is set) or the main file (legacy single-file mode). Required for Next.js App Router when using SWR or TanStack Query hooks, which can only run in Client Components. Has no effect and should not be used outside of RSC environments.",
          "type": "boolean"
        },
        "dateFormat": {
          "default": "Date",
          "description": "It determines how Date fields will be handled and what type they will have in models",
          "enum": ["Date", "string"],
          "type": "string"
        },
        "nullableStrategy": {
          "type": "string",
          "default": "ignore",
          "description": "Controls how OpenAPI 'nullable' is translated into TypeScript types",
          "enum": ["include", "nullableAsOptional", "ignore"]
        },
        "generationMode": {
          "type": "string",
          "default": "full",
          "description": "Controls whether to generate full API client code or only schemas",
          "enum": ["full", "schemas"]
        },
        "schemaDeclarationStyle": {
          "type": "string",
          "default": "interface",
          "description": "Controls whether object schemas are generated as interfaces or type aliases",
          "enum": ["interface", "type"]
        },
        "enumDeclarationStyle": {
          "type": "string",
          "default": "union",
          "description": "Controls whether plain string enums are generated as union types or TypeScript enums",
          "enum": ["union", "enum"]
        },
        "enumNamesStyle": {
          "type": "string",
          "default": "original",
          "description": "Controls how enum member names are formatted when generating TypeScript enum declarations. Only applies when enumDeclarationStyle is set to 'enum'.",
          "enum": ["original", "PascalCase"]
        },
        "testingFramework": {
          "description": "The test framework to use for generated mock stubs. `vitest` uses `vi.fn()`, `jest` uses `jest.fn()`. Requires `mocks` and `out` to also be set.",
          "type": "string",
          "enum": ["vitest", "jest"]
        },
        "queryParamsSerialization": {
          "$ref": "#/definitions/QueryParamsSerialization"
        },
        "responseShape": {
          "description": "Standardizes the value each generated operation returns. When omitted, each template keeps its current default return shape (non-breaking). 'body' returns just the response body (T). 'full' returns an APIResponse<T> wrapper exposing data, headers (template-native type) and statusCode.",
          "type": "string",
          "enum": ["body", "full"]
        },
        "forceSetup": {
          "description": "When `true`, overwrites the client setup file even if it already exists. Has no effect unless `clientSetup` is also set.",
          "type": "boolean",
          "default": false
        },
        "modifiers": {
          "$ref": "#/definitions/GlobalModifiers"
        },
        "exclude": {
          "$ref": "#/definitions/ExcludeOptions"
        }
      }
    },
    "Globals": {
      "additionalProperties": true,
      "description": "Main settings of the application",
      "type": "object",
      "required": ["out", "src"],
      "allOf": [{ "$ref": "#/definitions/GlobalsDefaults" }],
      "properties": {
        "src": {
          "description": "The url or path to the Open API spec file. Both JSON and YAML are supported",
          "type": "string"
        },
        "out": {
          "description": "The path to the file where the API would be generated. Use stdout if left empty.",
          "type": "string"
        },
        "hooksOut": {
          "description": "Output path for the generated reactive hooks file. Only applicable when using an L2 template (swr, tsq). When set, the reactive hook namespaces are written to this file and the main `out` file contains only the HTTP clients and TypeScript types. The hooks file imports the main file as `import * as API from './api'`. Use together with `useClient` for Next.js App Router. Requires `out` to also be set.",
          "type": "string",
          "examples": ["./src/generated/hooks.ts", "./src/api/hooks.ts"]
        },
        "mocks": {
          "description": "Output path for the generated mock/stub file. Requires `testingFramework` and `out` to also be set. When provided, a companion mock file is generated alongside the main client, exporting typed spy stubs for every operation and hook.",
          "type": "string",
          "examples": ["./src/__mocks__/api.ts", "./src/api/api.mock.ts"]
        },
        "clientSetup": {
          "description": "Output path for the write-once client setup file. Generated on the first run; never overwritten on subsequent runs unless `forceSetup` is set. For the `ky` template, the generated `api.ts` imports from this file and uses its exported `createKyConfig()` to initialise the ky instance with hooks. For other templates (`axios`, `xior`, `fetch`), it is a standalone scaffold showing how to configure the exported HTTP client — `api.ts` does not import it. Requires `out` to also be set.",
          "type": "string",
          "examples": ["./src/api.setup.ts", "./src/client/api.setup.ts"]
        }
      }
    },
    "MultiConfig": {
      "additionalProperties": true,
      "description": "Multi-config format. Allows generating multiple API clients in a single Swaggie run. Top-level properties (except 'configs') act as shared defaults for all entries and can be overridden per entry.",
      "type": "object",
      "required": ["configs"],
      "allOf": [{ "$ref": "#/definitions/GlobalsDefaults" }],
      "properties": {
        "configs": {
          "description": "List of individual Swaggie configs to run sequentially.",
          "type": "array",
          "items": { "$ref": "#/definitions/Globals" },
          "minItems": 1
        }
      }
    }
  },
  "oneOf": [
    {
      "$ref": "#/definitions/Globals"
    },
    {
      "$ref": "#/definitions/MultiConfig"
    }
  ]
}