swagger-typescript-api

You can generate an API client from an OpenAPI specification (OpenAPI 3.0, 2.0, JSON, or YAML) using the command line interface. You can run it directly via npx or install it as a dev dependency in your project.

# Run without installing
npx swagger-typescript-api generate --path ./swagger.json

# Or install locally first
npm install --save-dev swagger-typescript-api
npx swagger-typescript-api generate --path ./swagger.json

For programmatic control, import generateApi from swagger-typescript-api. This allows you to integrate the generation process directly into your build scripts or Node.js applications.

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

await generateApi({ input: path.resolve(process.cwd(), "./swagger.json") });

To use the library programmatically or to have the CLI available in your local project environment, install the package as a development dependency.

npm install --save-dev swagger-typescript-api

The swagger-typescript-api CLI provides two main subcommands: generate for creating TypeScript API clients from a Swagger/OpenAPI schema, and generate-templates for generating the .ejs templates used by the generator.

generate command

Use this command to transform a Swagger schema into a TypeScript API client. You can customize the output via various flags including HTTP client type, enum styles, and modularity settings.

generate-templates command

Use this command to generate the .ejs templates required for the generate command. This is useful if you want to customize how the code is generated.

To use the CLI, call the package name followed by the desired subcommand and its arguments.

The Hooks interface allows you to intercept and modify various stages of the code generation process. This is useful for custom naming, route manipulation, or schema parsing.

Key hooks include:

• onInit: The starting point after fetching the schema. Can modify the configuration.
• onPreParseSchema / onParseSchema: Intercept schema parsing.
• onFormatTypeName: Customize how model type names are generated.
• onFormatRouteName: Customize how route names (operationIds) are generated.
• onCreateRoute: Customize or ignore specific routes.
• onPreBuildRoutePath / onBuildRoutePath: Manipulate route path strings.
• onPrepareConfig: Customize the configuration object before it is sent to templates.

Use the generateApi function to programmatically trigger the API client generation process. It accepts a partial configuration object of type GenerateApiConfiguration["config"].

Key configuration options:

• debug: If set to true, enables maximum logging verbosity.
• silent: If set to true, suppresses all console output.

The hooks object in CodeGenConfig allows you to intercept and modify various stages of the generation process.

Available hooks include:

• onPreBuildRoutePath: Before building a route path.
• onBuildRoutePath: During route path construction.
• onInsertPathParam: When inserting a path parameter.
• onCreateComponent: To transform a SchemaComponent.
• onPreParseSchema: Before parsing a schema.
• onParseSchema: To modify the parsed schema.
• onCreateRoute: To modify route data.
• onInit: Called during initialization.
• onPrepareConfig: Called before configuration is finalized.
• onCreateRequestParams: To modify request parameters.
• onCreateRouteName: To modify the route name.
• onFormatTypeName: To customize type name formatting.
• onFormatRouteName: To customize route name formatting.

When calling generateApi, you can provide several input methods via GenerateApiParams:

• input: A string representing the local path to the swagger schema file.
• url: A string representing the URL of the swagger schema.
• spec: A literal Swagger/OpenAPI specification object.

All these interfaces extend GenerateApiConfiguration["config"], allowing you to pass any valid configuration option (like modular, enumStyle, httpClientType, etc.) alongside the input source.