swagger-codegen-runner

A fully-typed TypeScript library for running swagger-codegen-cli v3.

• ✅ Supports all generators — API clients, server stubs, documentation
• ✅ Full IntelliSense for additionalProperties — each generator has its own typed interface
• ✅ Granular copy rules — copy specific sub-directories of the output to different destinations
• ✅ Optional spec download from a local or remote server before codegen
• ✅ Works with Docker or a local Java installation
• ✅ Zero runtime dependencies — only Node.js built-ins

Prerequisites

| Mode | Requirement | |---|---| | Local Java | Java 8+ in PATH | | Docker | Docker Desktop or daemon running |

swagger-codegen-cli v3 itself is not bundled — you need either:

• A local clone/build of swagger-api/swagger-codegen (local Java mode)
• Docker (the image is pulled automatically)

Installation

npm install swagger-codegen-runner
# or
yarn add swagger-codegen-runner

Quick Start

import { run, type Config } from "swagger-codegen-runner";

const config: Config = {
  swaggerCodegenDir: "/path/to/swagger-codegen",
  projectDir: "/path/to/my-project",
  outputDestinationRelativePath: "src/app/shared/dto",

  generate: {
    language: "typescript-angular",
    inputSpec: "https://api.example.com/docs-json",
    additionalProperties: {
      ngVersion: "19",
      withInterfaces: false,
      modelPropertyNaming: "camelCase",
    },
  },
};

await run(config);

Configuration Reference

Config

| Field | Type | Default | Description | |---|---|---|---| | swaggerCodegenDir | string | required | Absolute path to the swagger-codegen repo root (JAR location). Not needed in Docker mode. | | projectDir | string | required | Absolute path to the destination project root. | | outputDestinationRelativePath | string | undefined | Relative path inside projectDir where the entire output is copied. Skips copy if omitted. Ignored when copyRules is set. | | copyRules | CopyRule[] | undefined | Granular copy rules. Takes precedence over outputDestinationRelativePath. | | cleanDestinationBeforeCopy | boolean | true | Empty the destination folder(s) before copying. Can be overridden per rule. | | useDocker | boolean | false | Run via Docker instead of local Java. | | dockerImage | string | swaggerapi/swagger-codegen-cli-v3:latest | Docker image to use. | | downloadSpec | DownloadSpecConfig | undefined | Download the spec before codegen. | | generate | CodegenGenerateOptions | required | Options forwarded to the generate command. |

CopyRule

Each rule copies a specific sub-directory of the generated output to a destination inside projectDir. Useful when you only want a subset of the output (e.g. just model/) or want to scatter different parts into separate locations.

| Field | Type | Default | Description | |---|---|---|---| | sourceSubPath | string | undefined | Sub-directory inside the generated output to copy from. Copies the entire output when omitted. | | destinationRelativePath | string | required | Relative path inside projectDir to copy into. | | cleanDestinationBeforeCopy | boolean | (inherits) | Override the top-level cleanDestinationBeforeCopy for this rule only. |

Example — copy only models:

copyRules: [
  { sourceSubPath: "model", destinationRelativePath: "src/app/shared/dto" },
]

Example — split models and API services into separate folders:

copyRules: [
  { sourceSubPath: "model", destinationRelativePath: "src/app/shared/dto" },
  { sourceSubPath: "api",   destinationRelativePath: "src/app/services/api" },
]

DownloadSpecConfig

| Field | Type | Default | Description | |---|---|---|---| | url | string | required | URL to fetch the spec from (http or https). | | outputPath | string | ./swagger.json | Local path where the spec is saved. | | required | boolean | true | Fail on download error (true) or fall back to inputSpec (false). |

CodegenGenerateOptions (common fields)

These fields apply to every generator.

| Field | Type | Default | Description | |---|---|---|---| | language | CodegenLanguage | required | Target generator. | | inputSpec | string | required | URL or local path to the spec file. | | outputDir | string | samples/client/output | Output path relative to swaggerCodegenDir. | | configFilePath | string | undefined | Write additionalProperties to this JSON file and use -c instead of inline flags. | | templateDir | string | undefined | Custom Mustache template directory (-t flag). | | models | string | undefined | Comma-separated list of model names to generate. | | apis | string | undefined | Comma-separated list of API operation tags to generate. | | systemProperties | Record<string, string> | undefined | JVM -D flags (e.g. { "io.swagger.parser.util.RemoteUrl.trustAll": "true" }). | | additionalProperties | (generator-specific) | undefined | Options specific to the chosen generator. See below. |

Supported Generators

Setting generate.language narrows additionalProperties to the typed interface for that generator.

API Clients

| Language | additionalProperties interface | Docs | |---|---|---| | typescript-angular | TypeScriptAngularAdditionalProperties | config-help | | typescript-axios | TypeScriptAxiosAdditionalProperties | config-help | | typescript-fetch | TypeScriptFetchAdditionalProperties | config-help | | java / jaxrs-cxf-client | JavaAdditionalProperties | config-help | | csharp / csharp-dotnet2 | CSharpAdditionalProperties | config-help | | go | GoAdditionalProperties | config-help | | python | PythonAdditionalProperties | config-help | | php | PhpAdditionalProperties | config-help | | kotlin-client | KotlinAdditionalProperties | config-help | | swift3 / swift4 / swift5 | SwiftAdditionalProperties | config-help | | ruby | RubyAdditionalProperties | config-help | | dart | DartAdditionalProperties | config-help | | scala | ScalaAdditionalProperties | config-help | | javascript / r | Record<string, string\|boolean\|number> | — |

Server Stubs

| Language | additionalProperties interface | Docs | |---|---|---| | spring / jaxrs-* / java-vertx / micronaut / inflector | SpringAdditionalProperties | config-help | | aspnetcore | CSharpAdditionalProperties | config-help | | go-server | GoAdditionalProperties | config-help | | python-flask | PythonAdditionalProperties | config-help | | kotlin-server | KotlinAdditionalProperties | config-help | | nodejs-server | NodeJsAdditionalProperties | config-help | | scala-akka-http-server | ScalaAdditionalProperties | — |

Documentation

| Language | Notes | |---|---| | html / html2 / dynamic-html | Static HTML documentation | | openapi / openapi-yaml | Re-emit the spec as JSON or YAML |

Documentation generators do not accept additionalProperties.

additionalProperties per Generator

For the complete and up-to-date list of options for any generator, run:

java -jar swagger-codegen-cli.jar config-help -l <language>

typescript-angular

| Property | Type | Default | Description | |---|---|---|---| | ngVersion | string | "4.3" | Angular version. Controls HttpClient, RxJS API, and module format. | | withInterfaces | boolean | false | Generate a TypeScript interface alongside each model class. | | taggedUnions | boolean | false | Use discriminated unions for models with a discriminator. | | kebabFileNaming | boolean | false | Use kebab-case file names (e.g. my-model.ts). | | modelPropertyNaming | "camelCase" \| "PascalCase" \| "snake_case" \| "original" | "camelCase" | Naming convention for model properties. | | npmName | string | — | Publish the generated code as this npm package name. | | npmVersion | string | "1.0.0" | npm package version. | | npmRepository | string | — | Private npm registry URL (set in publishConfig). | | snapshot | boolean | false | Append a timestamp suffix to the version. |

See example config →

typescript-axios

| Property | Type | Default | Description | |---|---|---|---| | withSeparateModelsAndApi | boolean | false | Place APIs and models in separate sub-folders. | | apiPackage | string | — | Sub-folder name for API classes (requires withSeparateModelsAndApi). | | modelPackage | string | — | Sub-folder name for model classes (requires withSeparateModelsAndApi). | | modelPropertyNaming | "camelCase" \| "PascalCase" \| "snake_case" \| "original" | "camelCase" | Naming convention for model properties. | | npmName / npmVersion / npmRepository / snapshot | — | — | Same as typescript-angular. |

See example config →

typescript-fetch

| Property | Type | Default | Description | |---|---|---|---| | supportsES6 | boolean | true | Emit ES6 import/export syntax. | | modelPropertyNaming | "camelCase" \| ... | "camelCase" | Naming convention for model properties. | | npmName / npmVersion / npmRepository / snapshot | — | — | Same as typescript-angular. |

java / jaxrs-cxf-client

| Property | Type | Default | Description | |---|---|---|---| | apiPackage | string | — | Package for API classes. | | modelPackage | string | — | Package for model classes. | | invokerPackage | string | — | Package for invoker/infrastructure classes. | | groupId / artifactId / artifactVersion | string | — | Maven coordinates. | | library | string | — | HTTP client library ("okhttp-gson", "retrofit2", "feign", "resttemplate"). | | java8 | boolean | false | Use Java 8 date/time types. | | useBeanValidation | boolean | false | Add JSR-303 Bean Validation annotations. | | dateLibrary | string | — | Date library ("java8", "threetenbp", "legacy"). |

Full list: java -jar swagger-codegen-cli.jar config-help -l java

spring / jaxrs-* / micronaut

Extends all java properties, plus:

| Property | Type | Default | Description | |---|---|---|---| | interfaceOnly | boolean | false | Generate controller interfaces instead of concrete classes. | | delegatePattern | boolean | false | Apply the delegator pattern to controllers. | | reactive | boolean | false | Target Spring WebFlux instead of Spring MVC. | | generateSpringApplication | boolean | false | Emit a complete Spring Boot application with main. | | useOptional | boolean | false | Use constructor injection with Optional<>. |

Full list: java -jar swagger-codegen-cli.jar config-help -l spring

csharp / aspnetcore

| Property | Type | Default | Description | |---|---|---|---| | packageName | string | — | Root namespace. | | packageVersion | string | "1.0.0" | Package version. | | targetFramework | string | — | .NET target framework (e.g. "net6.0"). | | nullableReferenceTypes | boolean | false | Enable nullable reference type annotations (C# 8+). | | asyncController | boolean | true | Generate async action methods. |

Full list: java -jar swagger-codegen-cli.jar config-help -l csharp

go / go-server

| Property | Type | Default | Description | |---|---|---|---| | packageName | string | — | Go module package name. | | generateGoMod | boolean | true | Emit a go.mod file. |

Full list: java -jar swagger-codegen-cli.jar config-help -l go

python / python-flask

| Property | Type | Default | Description | |---|---|---|---| | packageName | string | — | Python package name. | | packageVersion | string | "1.0.0" | Package version. | | projectName | string | — | Project name in setup.py. |

Full list: java -jar swagger-codegen-cli.jar config-help -l python

php

| Property | Type | Default | Description | |---|---|---|---| | packageName | string | — | Packagist name (e.g. "myorg/myapi"). | | invokerPackage | string | — | PSR-4 namespace. | | artifactVersion | string | "1.0.0" | Package version. |

Full list: java -jar swagger-codegen-cli.jar config-help -l php

kotlin

| Property | Type | Default | Description | |---|---|---|---| | packageName | string | — | Root package name. | | library | string | — | HTTP client ("jvm-okhttp4", "multiplatform"). |

Full list: java -jar swagger-codegen-cli.jar config-help -l kotlin-client

swift

| Property | Type | Default | Description | |---|---|---|---| | projectName | string | — | Swift module name. | | responseAs | string | — | Response library ("combine", "rxSwift", "promiseKit"). | | useURLSession | boolean | false | Use URLSession instead of Alamofire. |

Full list: java -jar swagger-codegen-cli.jar config-help -l swift5

ruby

| Property | Type | Default | Description | |---|---|---|---| | gemName | string | — | Ruby gem name. | | moduleName | string | — | Ruby module name. | | gemVersion | string | "1.0.0" | Gem version. |

Full list: java -jar swagger-codegen-cli.jar config-help -l ruby

nodejs-server

| Property | Type | Default | Description | |---|---|---|---| | npmName | string | — | npm package name. | | npmVersion | string | "1.0.0" | npm package version. |

Full list: java -jar swagger-codegen-cli.jar config-help -l nodejs-server

dart

| Property | Type | Default | Description | |---|---|---|---| | pubName | string | — | Dart package name. | | pubAuthor | string | — | Package author. | | pubHomepage | string | — | pub.dev homepage URL. |

Full list: java -jar swagger-codegen-cli.jar config-help -l dart

scala

| Property | Type | Default | Description | |---|---|---|---| | modelPackage | string | — | Model package name. | | mainClassName | string | — | Main class name. |

Full list: java -jar swagger-codegen-cli.jar config-help -l scala

Release Workflow

This project uses standard-version and Conventional Commits.

# Patch release (bug fixes)
npm run release

# Minor release (new features)
npm run release:minor

# Major release (breaking changes)
npm run release:major

standard-version will automatically:

1. Bump the version in package.json
2. Update CHANGELOG.md
3. Create a git commit and tag

Then push the tag to trigger the NPM publish GitHub Action:

git push --follow-tags origin main

Contributing

Contributions are welcome. Please open an issue or PR on GitHub.

Commit messages must follow Conventional Commits:

feat: add support for dart generator options
fix: correct outputDir resolution in Docker mode
docs: update spring additionalProperties table

License

MIT