Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generateApi
✓ import { generateApi } from 'swagger-typescript-api';
✗ const { generateApi } = require('swagger-typescript-api');
The library primarily uses named ESM exports. CommonJS require() syntax is not supported for v3+.
CLI Usage
✓ npx swagger-typescript-api generate --path ./swagger.json
✗ node_modules/swagger-typescript-api/lib/cli.js 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.
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();
swagger-typescript-api --version
Debug
Known issues
breakingThe package now explicitly requires Node.js version 20 or higher. Users on older Node.js versions will encounter compatibility issues or installation failures.fixUpgrade your Node.js environment to version 20 or newer (`nvm install 20 && nvm use 20`).
affects: >=13.0.0
breakingThe 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`.fixUpdate custom `securityWorker` implementations to align with the new return type signature, especially if asynchronous operations are performed.
affects: >=10.0.0
breakingVersions 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 `;`).fixUpgrade to `swagger-typescript-api@13.2.13` or newer to resolve the syntax errors in generated modular templates.
affects: 13.2.8 - 13.2.12
gotchaWhen 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.fixEnsure 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.
affects: All
gotchaWhen 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.fixPass custom properties via the `spec` object or use distinct, locally scoped variables for each `generateApi` call to ensure unique configurations per generation run.
affects: All
Errors
Common errors & fixes
ERR_PACKAGE_PATH_NOT_EXPORTED: No "exports" main defined in eta/package.json
A dependency conflict or premature upgrade of the `eta` templating engine, specifically `eta@4.0.1`, which had an incorrect package export configuration.
fixThis 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'.
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.
fixReview 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.'
Issues with specific template logic, especially with modular templates or custom template modifications, which can result in malformed TypeScript output.
fixVerify 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.
Audit
Dependencies
axiosoptionalOptional runtime dependency for the *generated* API client if '--axios' option is used.