{"id":16235,"library":"swagger-typescript-api","title":"Swagger TypeScript API Client Generator","description":"The `swagger-typescript-api` package is a code generation utility designed to create API client code and comprehensive TypeScript types directly from an OpenAPI Specification (Swagger) document. It offers robust support for both OpenAPI 3.0 and 2.0 definitions, handling specifications provided in JSON or YAML formats. Developers can configure the generated client to utilize either the native Fetch API or the widely-used Axios library, catering to diverse project requirements and existing HTTP client preferences. Currently at version 13.6.10, the project demonstrates an active development lifecycle with consistent patch releases that address bugs and introduce minor features. Its key differentiators include generating fully type-safe API interfaces, reducing manual boilerplate, and enabling a streamlined development workflow for interacting with RESTful APIs in TypeScript-driven applications, ensuring better maintainability and fewer runtime errors.","status":"active","version":"13.6.10","language":"javascript","source_language":"en","source_url":"https://github.com/acacode/swagger-typescript-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install swagger-typescript-api","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-typescript-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-typescript-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional runtime dependency for the *generated* API client if '--axios' option is used.","package":"axios","optional":true}],"imports":[{"note":"The library primarily uses named ESM exports. CommonJS require() syntax is not supported for v3+.","wrong":"const { generateApi } = require('swagger-typescript-api');","symbol":"generateApi","correct":"import { generateApi } from 'swagger-typescript-api';"},{"note":"The recommended way to use the CLI is via `npx` or a `package.json` script. Direct execution of `cli.js` is less portable.","wrong":"node_modules/swagger-typescript-api/lib/cli.js generate --path ./swagger.json","symbol":"CLI Usage","correct":"npx swagger-typescript-api generate --path ./swagger.json"},{"note":"Type imports for configuration options are available for advanced customization.","symbol":"API Options","correct":"import type { IExtendedOptions } from 'swagger-typescript-api';"}],"quickstart":{"code":"import * as path from \"node:path\";\nimport * as process from \"node:process\";\nimport { generateApi } from \"swagger-typescript-api\";\n\nconst swaggerSpecPath = path.resolve(process.cwd(), \"./swagger.json\");\nconst outputPath = path.resolve(process.cwd(), \"./src/api\");\n\n// A minimal example showing how to generate an API client\n// Ensure a swagger.json file exists in the current working directory\n// For more complex configurations (e.g., custom templates, Axios vs Fetch),\n// refer to the official documentation and API options.\n\nasync function main() {\n  try {\n    await generateApi({\n      name: \"Api.ts\", // Output file name\n      output: outputPath, // Output directory\n      input: swaggerSpecPath, // Path to OpenAPI/Swagger JSON/YAML file\n      httpClient: \"fetch\", // Or 'axios'\n      generateClient: true, // Whether to generate the client methods\n      extractEnums: true, // Extract enums to separate types\n      moduleNameFirstTag: true, // Group operations by the first tag in the module name\n    });\n    console.log(`API client successfully generated at ${outputPath}/Api.ts`);\n  } catch (error) {\n    console.error(\"Error generating API client:\", error);\n    process.exit(1);\n  }\n}\n\nmain();","lang":"typescript","description":"This quickstart demonstrates how to programmatically generate a Fetch-based API client from a local `swagger.json` file, outputting it to a specified directory."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer (`nvm install 20 && nvm use 20`).","message":"The package now explicitly requires Node.js version 20 or higher. Users on older Node.js versions will encounter compatibility issues or installation failures.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Update custom `securityWorker` implementations to align with the new return type signature, especially if asynchronous operations are performed.","message":"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`.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade to `swagger-typescript-api@13.2.13` or newer to resolve the syntax errors in generated modular templates.","message":"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 `;`).","severity":"breaking","affected_versions":"13.2.8 - 13.2.12"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","cause":"A dependency conflict or premature upgrade of the `eta` templating engine, specifically `eta@4.0.1`, which had an incorrect package export configuration.","error":"ERR_PACKAGE_PATH_NOT_EXPORTED: No \"exports\" main defined in eta/package.json"},{"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.","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.","error":"Property 'someProperty' does not exist on type 'SomeType'."},{"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.","cause":"Issues with specific template logic, especially with modular templates or custom template modifications, which can result in malformed TypeScript output.","error":"TypeScript syntax errors in generated client, e.g., 'Expected ;' or 'Expression expected.'"}],"ecosystem":"npm"}