swagger-core's readme is a release log with one row per patch

The readme is a release log in table form

The structure of the readme is unusual: the largest element on the page is a compatibility table, and it lists one row per patch release.

Each row carries a version, a release date, the specification versions the release supports, a link to that version's own tag, and a status.

The table runs from the current stable release back through roughly three dozen earlier ones, and in the range shown every row reports the same specification compatibility and the same supported status.

So the readme tells you three things rather than one. Which specification generation the library implements, that the specification it tracks has been revised several times since 2010, and the exact release you would pin.

That last column is unusual. Most projects list a support policy; this one lets you pick a patch release and have the table tell you what it corresponds to.

Every release gets a row and a tag of its own

Reading the dates in the table gives the cadence without needing a changelog.

The latest rows of the table show three releases in August 2026, spaced about two weeks apart, and v3.0.0 has since been released on 2026-10-28. Earlier in the year, March and April 2026 each had three releases. A year earlier, 2.2.31 and 2.2.32 came a day apart, on 2025-05-13 and 2025-05-14.

So this is a project that ships on a need-to-fix basis rather than on a calendar, and the table is the evidence, since the gaps are irregular and the changes are small.

The release titles match that pattern too. They are a version number and the word released, with an exclamation mark, and nothing about what changed. For what changed, each table row links to the release's tag, and the repository keeps a CHANGELOG.md at the root.

Two artifact families for two namespace generations

There is a note near the top of the readme that determines which artifact you actually add to your build.

Since a specific version in the 2.1 line, the library also supports the Jakarta namespace. There is a parallel set of artifacts carrying a jakarta suffix, providing the same functionality as the unsuffixed ones, which the readme names as the older namespace.

And the summary line states the scope plainly: it is a Java implementation of the specification, currently supporting version 2 of the REST annotations interface, in both namespaces.

That means the dependency choice is a fork in the road rather than a version bump. The same features exist twice, and the suffix is what selects which one your runtime can load, because the two namespace generations are not interchangeable at compile time.

The old specification still has its own branch

The first note in the readme redirects anyone who wants the previous generation of the specification.

If you are looking for the 1.5 line and the 2.0 version of the specification, the readme points at a branch named for that line rather than at a release.

So the repository carries two long-lived lines: the one this readme documents, which implements the current specification, and a branch that still implements the old one.

That arrangement matters for anyone doing an upgrade. The gap between the two is not a version number; it is a different branch with different artifacts and a different specification generation behind it, and the readme's first line is the instruction to switch branches rather than to upgrade versions.

Support for the current specification version arrived at 2.2.0

The third note records a feature boundary by version.

From the 2.2.0 line onwards, the library supports version 3.1 of the specification, and the readme links a separate wiki page describing it.

Two things follow. The current three-point-something support is not the same as the latest point release of the specification; the newest line is the one that added it. And the details live on the wiki rather than in the readme, consistent with the rest of the documentation strategy.

The compatibility table, meanwhile, marks every release in the shown range as compatible with the 3.x family, without distinguishing which point of 3.x a given release implements. So the table answers the question of whether a release is in the right generation, and the wiki page answers the question of how much of the newest generation it covers.

Documentation is a wiki, and the readme only points at it

The readme opens with notes, links and the compatibility table rather than code examples.

There is a getting started guide, a wiki, and a sentence describing the wiki as the place holding documentation, samples and contributions.

What the readme does contain is a badge for the published artifact on the Maven repository, under the v3 group, which is the one pointer that matters for someone deciding whether the library exists where they expect it to.

The project description frames the repository as examples and server integrations for generating the specification, so the examples being in the wiki rather than in the repository is consistent.

That documentation model is why the readme can lead with notes and a table.

The build is a wrapper and a modules directory

The repository layout describes a conventional Maven multi-module build, with two details worth noting.

The build is driven by a committed wrapper, for both the Unix and Windows launchers, with its configuration directory present. That means a contributor's first build does not depend on having a matching Maven installation.

And there is a modules directory rather than a single project.

The remaining root files are the ones you would expect from an Apache-licensed project at this scale: a licence file and a notice file, a changelog, a continuous integration directory, and a dependency scanning configuration.

There is also a single image file at the root, which is a small human signal in a repository whose whole subject is generated documentation.

Editorial conclusion

swagger-core fits a Java service that serves an OpenAPI description from annotations or interfaces and needs to keep generating it as the specification moves. It does not fit a team that wants one artifact to cover both namespace generations, because the two are published separately. Before adopting, pick the artifact family that matches your runtime, check whether you need the 3.1 support that arrived with the 2.2.0 line, and read the compatibility table rather than the version number, since the table is what the project maintains.

Frequently asked questions

Official sources

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