Swagger TypeScript Codegen

Common errors

• TypeError: Cannot read properties of undefined (reading 'info')

  cause The provided `swagger` object is malformed, missing the crucial `info` property, or the file failed to load/parse correctly resulting in an empty or invalid object.
  fix Verify the `swagger` JSON file's content and structure against the Swagger 2.0 specification. Ensure `fs.readFileSync` successfully reads the file and `JSON.parse` does not throw an error before passing the object to `CodeGen`.

• TypeError: CodeGen.getTypescriptCode is not a function

  cause Incorrectly importing or accessing the `CodeGen` object, often due to trying a default ESM import (`import CodeGen from '...'`) or an incorrect named import that doesn't resolve the static methods.
  fix Use the documented CommonJS import pattern: `const CodeGen = require('swagger-typescript-codegen').CodeGen;` to ensure `CodeGen` is correctly resolved as an object with the static `getTypescriptCode` method.

• Error: ENOENT: no such file or directory, open 'swagger/spec.json'

  cause The specified Swagger specification file (`swagger/spec.json` in the example) does not exist at the given path relative to where the script is being executed.
  fix Double-check the file path provided to `fs.readFileSync`. Ensure the file exists and the path is correct, or use an absolute path for robustness. Consider adding `process.cwd()` to construct the full path.

Warnings

• gotcha This tool is primarily designed for Swagger 2.0 specifications (OpenAPI 2.0). While it might process some OpenAPI 3.x definitions, full compatibility is not guaranteed, and unexpected behavior or missing features may occur.
  Fix: Ensure your input specification strictly adheres to Swagger 2.0. If using OpenAPI 3.x, thoroughly test the generated code for correctness or consider alternative tools designed specifically for OpenAPI 3.x.
• gotcha The generated TypeScript code relies on `superagent` for HTTP requests. If your project uses a different HTTP client (e.g., Axios, Fetch API), you will need to provide custom templates to integrate your preferred client library, or manually adjust the generated code.
  Fix: Utilize the `CodeGen.getCustomCode` function with tailored Mustache templates (`class`, `method`, `type`) to generate code that incorporates your desired HTTP client and its API calls.
• gotcha The `imports` option in `getTypescriptCode` is strictly for adding TypeScript definition file (`.d.ts`) imports or `/// <reference />` directives for type augmentation, not for importing JavaScript modules that the generated client might depend on.
  Fix: For actual module dependencies of the generated client (e.g., `superagent` itself if not bundled), you will need to manually ensure they are installed and correctly bundled/imported in your consuming application. The `imports` option specifically handles type references.
• deprecated The primary usage examples and documentation show `require` for importing `CodeGen`. While Node.js supports ESM, the package's direct usage of `require` for its exports suggests a CJS-first design. Attempting ESM imports like `import { CodeGen } from 'swagger-typescript-codegen'` might not work or could require specific Node.js loader configurations.
  Fix: Stick to `const CodeGen = require('swagger-typescript-codegen').CodeGen;` for consistent and reliable module loading, especially in Node.js environments. If working in a pure ESM context, manual wrapping or careful configuration might be needed.

Install

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

Imports

• CodeGen
  wrong:

  import { CodeGen } from 'swagger-typescript-codegen';

  correct:

  const CodeGen = require('swagger-typescript-codegen').CodeGen;

  The primary API is exposed via CommonJS `require` for `CodeGen.getTypescriptCode` and `CodeGen.getCustomCode`. While an ES module import might be attempted, it is not the documented or typical usage.
• getTypescriptCode
  wrong:

  import { getTypescriptCode } from 'swagger-typescript-codegen';

  correct:

  CodeGen.getTypescriptCode({ /* options */ });

  This is a static method of the `CodeGen` object, not a top-level named export. It must be called on the imported `CodeGen` object.
• getCustomCode
  wrong:

  import { getCustomCode } from 'swagger-typescript-codegen';

  correct:

  CodeGen.getCustomCode({ /* options */ });

  Similar to `getTypescriptCode`, this is a static method of the `CodeGen` object used for custom template-based generation and must be called on the imported `CodeGen` object.

Quickstart

This snippet demonstrates how to synchronously load a Swagger JSON specification from a file, parse it, and then use `swagger-typescript-codegen` to generate a TypeScript client class named 'TestClient', logging the output to the console.

var fs = require("fs");
var CodeGen = require("swagger-typescript-codegen").CodeGen;

// Assuming 'swagger/spec.json' exists in the project root
// or provide an absolute path.
var swaggerFilePath = "swagger/spec.json";

try {
  var swagger = JSON.parse(fs.readFileSync(swaggerFilePath, "UTF-8"));
  var tsSourceCode = CodeGen.getTypescriptCode({
    className: "TestClient", // Renamed for clarity
    swagger: swagger,
    // Example of importing a typings file if needed, adjust path as necessary
    imports: ["./typings/my-custom-types.d.ts"]
  });
  console.log(tsSourceCode);
} catch (error) {
  console.error(`Failed to generate code: ${error.message}`);
  if (error.code === 'ENOENT') {
    console.error(`Ensure '${swaggerFilePath}' exists and is accessible.`);
  } else if (error instanceof SyntaxError) {
    console.error(`Swagger file '${swaggerFilePath}' is not valid JSON.`);
  }
}