Swagger Codegen: template-driven client and server generation from an OpenAPI spec

What Swagger Codegen does that hand-written SDKs cannot keep up with

The problem is drift. An API definition changes, and every consumer of that API has to notice and update by hand: the Java client, the TypeScript client, the Python client, the server stub, the reference documentation. Swagger Codegen exists to make that update a build step. Given an OpenAPI or Swagger definition, it produces API client libraries, server stubs and documentation automatically, according to the README. The audience is teams that already treat the spec as the source of truth and want generated artefacts to follow it, rather than platform teams maintaining a single SDK for one language.

The breadth is the selling point. The README lists API clients for ActionScript, Ada, Apex, Bash, C#, C++, Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell, Java, Kotlin, Lua, Node.js, Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift and TypeScript, with multiple framework variants inside several of those. Server stubs cover a smaller but still wide set, including Java, Kotlin, Go, Python Flask, NodeJS, Ruby, Rust and Scala. There are also generators for HTML and Confluence Wiki documentation, Apache2 configuration files, and JMeter. That list is the reason the project is still referenced years after its first release: few single tools cover that many targets from one template engine.

How the template engine turns a spec into code

The mechanism is template-driven. The repository's primary language is Mustache, and the generators are organised as modules under modules/. The CLI parses the OpenAPI or Swagger definition into an internal model, then a language-specific generator walks that model and renders Mustache templates into files. The language-specific parts are the templates plus the generator class that maps spec concepts onto template variables; the parsing and the model are shared.

That split is why adding a target is tractable and why output quality varies between targets. A generator that has been maintained closely will map discriminators, enums and nullable fields sensibly; a rarely touched one may render a compilable but awkward client. The README's supported-language list is a list of what exists, not a statement that every entry is equally current. The repository layout reinforces this: modules/ holds the core library, the CLI, the Maven plugin and the swagger-generator, while samples/ holds generated output for client, server, documentation, dynamic-html and html variants. Reading a sample for your target language before generating is the cheapest way to see what the templates actually emit.

The README carries one warning that belongs in the architecture discussion rather than a footnote: if the OpenAPI description or Swagger file comes from an untrusted source, review the artefact before using Swagger Codegen, because code injection may occur. This is inherent to a tool whose job is to write code from a document. Treat a third-party spec the way you would treat third-party code.

Installing the CLI and generating your first client

The README's quick example builds the CLI from source with Maven and then runs it against the public petstore definition to produce a PHP client. The clone, build and generate steps are given as a single sequence, and the output directory is /var/tmp/php_api_client.

git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
   -i https://petstore.swagger.io/v2/swagger.json \
   -l php \
   -o /var/tmp/php_api_client

The README notes that on Windows the last command changes to a single line with backslashes in the paths:

java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i https://petstore.swagger.io/v2/swagger.json -l php -o c:\temp\php_api_client

If you do not want to build from source, the README points at the latest release JAR on maven.org and gives the 2.4.46 artefact path as the example download. Note the group id difference the README calls out: 2.X publishes under io.swagger, 3.X under io.swagger.codegen.v3. Picking the wrong one is the most common way to end up with a CLI that does not recognise an OpenAPI 3.0 document. To see the general options a generator accepts, the README shows running the JAR with help rather than a generate subcommand.

The Docker route is documented separately in docs/docker.md, and the repository's Dockerfile shows what the image does: it starts from maven:3-eclipse-temurin-11-alpine, installs bash, copies the CLI, core and plugin modules plus pom.xml, and pre-compiles the CLI with a Maven package command scoped to modules/swagger-codegen-cli. The entrypoint is docker-entrypoint.sh and the default command is help, so a bare container run prints usage rather than generating anything.

The Maven plugin, and why version pinning matters more here than usual

For Java projects the CLI is often the wrong integration point. The repository contains modules/swagger-codegen-maven-plugin, and the Dockerfile copies it alongside the CLI, which tells you it is a first-class part of the build rather than an afterthought. Wiring generation into a Maven lifecycle means the client is regenerated whenever the build runs, so a spec change surfaces as a compile error instead of a stale dependency. The trade-off is that generated sources enter your build output and your review process; teams that commit generated code and teams that generate on every build end up with very different diffs.

Version pinning deserves more attention than it usually gets with this project. The README states plainly that both 2.X and 3.X lines are available and independently maintained, that their group ids differ, and that OpenAPI 3.0.X is supported from the 3.X version only. The compatibility table in the README lists 3.0.71 as current stable for the 3.X line and 2.4.46 as current stable for 2.X, with 3.0.72-SNAPSHOT and 2.4.47-SNAPSHOT as upcoming minor releases. The release history shows the 3.X line moving: v3.0.80 and v3.0.81 in May 2026, v3.0.82 in August 2026. The last push to the repository was on 2026-08-18, and the repository is not archived.

A generated client is a dependency you did not write, so pin the generator version the same way you pin a library. Upgrading the generator can change method signatures, model class names and serialisation behaviour across an entire SDK in one step. That is a larger blast radius than most dependency bumps.

Where Swagger Codegen is the wrong tool

The code injection warning is the sharpest limitation, and it is easy to dismiss until you consider the workflow it describes. Specs are frequently pulled from a vendor URL, a partner repository or a public registry. Swagger Codegen reads that document and writes files, and the README says code injection may occur if the source is untrusted. There is no sandbox mentioned in the README, and no validation step that stands between the spec and the generated files. If your process ingests third-party specs automatically, that is a supply chain decision, not a formatting preference.

Second, the two version lines are a real cost. A team on OpenAPI 3.0 cannot use the 2.X line at all, and a team that started on 2.X and needs OpenAPI 3.0 support is looking at a migration to a different group id, not a version bump. The README's own note that the document it sits in refers to version 2.X, with a pointer to a separate branch for 3.X, is a hint about how much context lives in each line.

Third, the templates are the product, and templates age. A generator for a framework that has since changed its idioms will still produce code in the old idiom, because nothing forces a template update. The README lists Swift 2.x through 5.x and AngularJS alongside Angular2.x in the same list, which is a snapshot of accumulated history rather than a curated set. If your target is a niche entry in that list, budget time to read the templates before you trust the output.

Swagger Codegen vs OpenAPI Generator, and the 2.X vs 3.X question

The comparison people search for is Swagger Codegen vs OpenAPI Generator, and the difference is governance and lineage rather than a feature checklist. OpenAPI Generator is a fork of Swagger Codegen; the practical consequence is that the two projects have diverged in template maintenance and in how quickly each absorbs new language and framework targets. The README here does not discuss the fork, so the honest position is that you should compare the two on the specific generator you need: check the template for your target language in both, generate the same spec with both, and diff the output. That test takes an afternoon and answers the question better than a feature table.

The 2.X vs 3.X question is internal to this project and has a clear answer in the README. If your definition is OpenAPI 3.0.X, you need 3.X, group id io.swagger.codegen.v3. If it is Swagger 2.0 or earlier, both lines work and the choice is about which templates you prefer. The README's compatibility table shows 3.X covering 1.0 through 3.0 and 2.X covering 1.0 through 2.0. There is no path where 2.X reads an OpenAPI 3.0 document.

Licence and the cost of staying current

Swagger Codegen is Apache-2.0. The Dockerfile carries a comment that the LICENSE file is copied in because it is required from a licensing standpoint, which is consistent with the licence's notice requirements. Generated code inherits whatever the templates and any embedded dependencies impose, and the README does not discuss the licence status of generated output. If you ship a generated SDK to customers, that is worth confirming with your own legal review rather than assuming the generator's licence settles it. Nothing here is legal advice.

Upgrade cost is the ongoing expense. The 3.X line has seen patch releases through 2026, with v3.0.82 on 2026-08-04 and the last push on 2026-08-18. Each upgrade can alter generated output, so the realistic process is to regenerate against a pinned version in CI, inspect the diff, and only then move the pin. The repository provides samples/ with generated client, server and documentation output, which gives you a baseline for what a given generator version produces. If your generated code is committed, that diff is your upgrade review; if it is generated at build time, your test suite is.

Editorial conclusion

Adopt Swagger Codegen if you need a generated client or server stub in one of the many languages the README lists and you are willing to pin a version, because the 2.X and 3.X lines are maintained separately and their group ids differ. Do not adopt it if your spec comes from an untrusted source, since the README warns that code injection may occur, or if you expect OpenAPI 3.0.X support from the 2.X line, which does not have it. Before committing, verify which line you need, check that your target language appears in the supported list, and confirm the generator output against your own spec rather than the petstore sample.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. swagger-api/swagger-codegen on GitHub