Swagger TypeScript API Client Generator

Common errors

• ERR_PACKAGE_PATH_NOT_EXPORTED: No "exports" main defined in eta/package.json

  cause A dependency conflict or premature upgrade of the `eta` templating engine, specifically `eta@4.0.1`, which had an incorrect package export configuration.
  fix This was internally fixed by downgrading `eta` to `3.5.0`. Ensure you are on a `swagger-typescript-api` version that has this fix (e.g., `13.2.15` or newer).

• Property 'someProperty' does not exist on type 'SomeType'.

  cause Mismatch between the OpenAPI specification and the generated TypeScript types, often due to complex schema structures, `oneOf`/`anyOf`/`allOf` issues, or incorrect handling of nullable fields.
  fix Review your OpenAPI specification for correctness and consistency. Utilize `swagger-typescript-api` options like `extractEnums`, `extractRequestBody`, `extractResponseBody`, and `primitiveTypeConstructs` to fine-tune type generation. Consider using `prettier` post-generation to catch syntax issues.

• TypeScript syntax errors in generated client, e.g., 'Expected ;' or 'Expression expected.'

  cause Issues with specific template logic, especially with modular templates or custom template modifications, which can result in malformed TypeScript output.
  fix Verify the `swagger-typescript-api` version; if using an older version (e.g., 13.2.8-13.2.12) which had known modular template bugs, upgrade. If using custom templates, carefully review the `.eta` files for syntax errors or incorrect output patterns.

Warnings

• breaking The package now explicitly requires Node.js version 20 or higher. Users on older Node.js versions will encounter compatibility issues or installation failures.
  Fix: Upgrade your Node.js environment to version 20 or newer (`nvm install 20 && nvm use 20`).
• breaking The signature for the `securityWorker` function, used in custom `http-client.eta` templates, changed in v10.0.0. It now supports returning a `Promise<RequestParams | void>` in addition to `RequestParams | void`.
  Fix: Update custom `securityWorker` implementations to align with the new return type signature, especially if asynchronous operations are performed.
• breaking Versions 13.2.8 through 13.2.12 had issues generating invalid TypeScript code when using modular templates, specifically with object method syntax (`:` and `,`) instead of class property syntax (`=` and `;`).
  Fix: Upgrade to `swagger-typescript-api@13.2.13` or newer to resolve the syntax errors in generated modular templates.
• gotcha When using custom templates (e.g., `.eta` files), the generator automatically removes `import` statements for symbols that are not explicitly used within the template. This can lead to confusion if an import is intended for global types or future use.
  Fix: Ensure that any imported symbols in custom templates are actively referenced to prevent them from being stripped. If an import is truly global and not directly used, consider alternative methods for inclusion or wrap it in a dummy usage.
• gotcha When generating multiple API clients programmatically, using the `config` object for custom properties can lead to unexpected behavior due to its global reference. Subsequent generations might use outdated `config` values.
  Fix: Pass custom properties via the `spec` object or use distinct, locally scoped variables for each `generateApi` call to ensure unique configurations per generation run.

Install

• npm install swagger-typescript-api npm
• yarn add swagger-typescript-api yarn
• pnpm add swagger-typescript-api pnpm

Imports

• generateApi
  wrong:

  const { generateApi } = require('swagger-typescript-api');

  correct:

  import { generateApi } from 'swagger-typescript-api';

  The library primarily uses named ESM exports. CommonJS require() syntax is not supported for v3+.
• CLI Usage
  wrong:

  node_modules/swagger-typescript-api/lib/cli.js generate --path ./swagger.json

  correct:

  npx swagger-typescript-api generate --path ./swagger.json

  The recommended way to use the CLI is via `npx` or a `package.json` script. Direct execution of `cli.js` is less portable.
• API Options

  import type { IExtendedOptions } from 'swagger-typescript-api';

  Type imports for configuration options are available for advanced customization.

Quickstart

This quickstart demonstrates how to programmatically generate a Fetch-based API client from a local `swagger.json` file, outputting it to a specified directory.

import * as path from "node:path";
import * as process from "node:process";
import { generateApi } from "swagger-typescript-api";

const swaggerSpecPath = path.resolve(process.cwd(), "./swagger.json");
const outputPath = path.resolve(process.cwd(), "./src/api");

// A minimal example showing how to generate an API client
// Ensure a swagger.json file exists in the current working directory
// For more complex configurations (e.g., custom templates, Axios vs Fetch),
// refer to the official documentation and API options.

async function main() {
  try {
    await generateApi({
      name: "Api.ts", // Output file name
      output: outputPath, // Output directory
      input: swaggerSpecPath, // Path to OpenAPI/Swagger JSON/YAML file
      httpClient: "fetch", // Or 'axios'
      generateClient: true, // Whether to generate the client methods
      extractEnums: true, // Extract enums to separate types
      moduleNameFirstTag: true, // Group operations by the first tag in the module name
    });
    console.log(`API client successfully generated at ${outputPath}/Api.ts`);
  } catch (error) {
    console.error("Error generating API client:", error);
    process.exit(1);
  }
}

main();