Swagger Codegen: master serves 2.X, the compatibility table stops at 3.0.71

Mustache templates are the product, not the Java engine

The engine's job is narrow: parse an OpenAPI or Swagger definition and hand the result to templates. Everything a generator emits comes out of a Mustache template, from a Bash client to a Spring stub, and the repository's recorded primary language is Mustache rather than Java. That tells you where a defect lives before you start looking for it.

If a generated client is wrong, the fix belongs in a template rather than in the parser, and regenerating without your template change reproduces the same defect without complaint. Reference output sits under samples/, split into client, server, documentation, dynamic-html, html, html2, config, yaml and custom-tests, so a regeneration has something to compare against before it reaches a commit.

Documentation generators are the narrowest part of the offering: HTML and Confluence Wiki, with Apache2 listed under Configuration files and JMeter under Others. A team that only needs a browsable API reference does not need the client and server matrix at all, and it feeds the same spec file either way.

master carries 2.X, and OpenAPI 3.0 lives on another branch

On the default branch, the README opens its versioning section by saying the document refers to version 2.X and sending you to a 3.0.0 branch for 3.X. Both lines exist and are independently maintained. They do not share a group id: 2.X publishes under io.swagger, 3.X under io.swagger.codegen.v3, and OpenAPI 3.0.X is supported from the 3.X line only.

That has a concrete cost. Clone master, follow the quick example, and you are running 2.4.x, which cannot process a document written in OpenAPI 3.0. The jar link in the getting started section resolves to the 2.4.46 path on maven.org for the same reason. Anyone who has already moved their spec to OpenAPI 3.0 has to work from the other branch or from a 3.x artifact, and nothing in the clone command says so.

Keeping a 2.x line is not redundant, since both tables list compatibility with spec versions 1.0, 1.1 and 1.2 alongside 2.0, and the README notes the OpenAPI Specification has had three revisions since 2010.

The compatibility table stops at 3.0.71 while the tags reach v3.0.82

The README's compatibility table names 3.0.71, dated 2025-07-03, and 2.4.46, dated 2025-06-30, as the current stable releases, and previews 3.0.72-SNAPSHOT and 2.4.47-SNAPSHOT as the upcoming minor releases. The tags have moved past that: the recent releases include v3.0.84 from 2026-11-02, v3.0.83 from 2026-10-26 and v2.4.53 from 2026-10-22.

Nothing in the table is wrong about which line handles OpenAPI 3.0, so the decision still comes out right. The number goes stale, and a reader who pins 3.0.71 because the README called it current is thirteen patch releases behind the newest tag. The table hands off to docs/compatibility.md and docs/versioning.md for the full listing, and those are the files to open before you pin anything.

Getting started shows the same lag: it offers a direct jar download labelled as the latest release and resolves to the 2.4.46 path. Read that as the 2.x convenience download rather than as the newest artifact on the 3.x line.

mvn package, then java -jar with -i, -l and -o

Three setup guides sit under docs/: prerequisites, building and docker. The quick example builds from source, and the three flags matter more than the language choice. -i is the spec, -l names the generator, -o is where the output lands.

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

Expect a PHP client in /var/tmp/php_api_client when it finishes, generated from the Petstore document in the example. On Windows the same call uses backslash paths and a different output directory.

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

mvn clean package builds every module, and the repository ships an mvnw wrapper when the system Maven is not the one you want. If you only need the command line tool, the 2.4.46 jar download skips the build, and on the 3.x line you take the artifact from that line's coordinates instead.

The image runs on Temurin 11 and keeps Maven's cache in a volume

The Dockerfile builds on maven:3-eclipse-temurin-11-alpine, so Java 11 is what runs the generator rather than what your generated code targets. It adds bash, then copies four modules one at a time so Docker can reuse layers between minor versions, which is why a version bump does not invalidate the whole cache. The Maven repository at ${MAVEN_HOME}/.m2/repository is declared as a volume, so dependency downloads survive container restarts instead of repeating on every run.

Two lines in that file matter to a reader. The LICENSE file is copied in with a comment saying it is required from a licensing standpoint, so an image you redistribute carries the Apache-2.0 text with it. And a comment says swagger-generator is not included and is available as swaggerapi/swagger-generator, although the Dockerfile still copies modules/swagger-generator.

run-in-docker.sh and new.sh at the repository root are the local wrappers.

A spec from an untrusted source becomes code in your tree

The README carries an explicit warning: if the OpenAPI Description or Swagger file is obtained from an untrusted source, review the artefact before generating the API client, server stub or documentation, because code injection may occur.

Values from the document are interpolated into generated source through those templates, so a spec is executable content by the time it lands in your repository. Review is the mitigation the README names, and it is a manual step by hand. A client built from a third-party spec is code somebody has to read.

That bites hardest with the server stub generators, where a stub is meant to be edited by your team and merged. A client you generate and never touch still ships inside your application, which is the argument for reading the diff before the first commit rather than after the first problem report.

Two maintained lines under Apache-2.0, and a push on 2026-09-29

master was last pushed on 2026-11-02. The three most recent releases are v3.0.84 from 2026-11-02, v3.0.83 from 2026-10-26 and v2.4.53 from 2026-10-22, and there is no CHANGELOG.md at the repository root, so a release note is either on the release page or reconstructed from the diff.

The project itself is under Apache-2.0.

For anything else, the README points contributors at CONTRIBUTING.md, at open issues carrying the help wanted label, and at the project wiki and its FAQ page. Those are the places to take a generator that produces the wrong output, since the template fix and the pull request are the same object here.

Editorial conclusion

Choose Swagger Codegen when a spec is the source of truth and you want a client, a stub or an HTML reference generated from it, and pin a 3.x tag if your document is OpenAPI 3.0, because the default branch still serves 2.X. Do not reach for it when the spec comes from someone you do not trust, since the README itself warns that code injection may occur, and do not trust the compatibility table to tell you which version is current. Check docs/versioning.md and the branch you cloned first, then run the generate command once by hand against a spec you own before wiring it into a build.

Frequently asked questions

Official sources

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