# Swagger Core: Generating OpenAPI 3.x Definitions from Java JAX-RS Code

> Swagger Core is the Java library that reads JAX-RS annotations and produces an OpenAPI document at runtime. It is a build-time dependency for API producers, not a UI, and its release cadence and jakarta artifact split are the two things to understand before adopting it.

**swagger-api/swagger-core** — Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API

- Repository: https://github.com/swagger-api/swagger-core
- Website: http://swagger.io
- Stars: 7,529 · Forks: 2,260
- Language: Java
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/swagger-api-swagger-core

## What Swagger Core actually produces, and who consumes it

Swagger Core is a Java implementation of the OpenAPI Specification. That sentence from the README is the whole scope. It reads the JAX-RS annotations on your resource classes and the Java types on your request and response objects, then emits an OpenAPI document describing those endpoints. The output is a specification file or a served JSON/YAML document, not a web page.

That distinction matters because the name Swagger covers several products. Swagger UI renders a document in a browser. Swagger Editor lets you write one by hand. Swagger Core sits upstream of both: it is the piece that derives the document from code you already have. If you are building a REST service in Java with JAX-RS and you want an accurate specification without maintaining a separate YAML file, this is the library that does that job.

The audience is therefore narrow and specific. Backend Java teams on JAX-RS2, using either the javax or jakarta namespace, who want the specification to follow the code rather than the other way around. Teams that write the OpenAPI file first and generate stubs from it are working in the opposite direction, and Swagger Core is not the tool for that.

## How the JAX-RS annotations become an OpenAPI 3.x document

The mechanism is annotation scanning plus type introspection. Your resource class carries JAX-RS annotations such as the HTTP method and path; Swagger Core reads those to establish operations and paths. It then walks the parameter and return types to build the schema components, which is why the generated document tracks your actual Java model classes instead of a hand-written description of them.

The README states that current version supports JAX-RS2, in both the javax and jakarta namespaces. Since version 2.1.7 the project has published a parallel set of artifacts with the -jakarta suffix, providing the same functionality as the unsuffixed (javax) artifacts. This is not a cosmetic packaging detail. A jakarta application cannot resolve javax annotations, so the artifact you pick has to match the namespace your container and your other dependencies use.

OpenAPI revision support is versioned separately from the library version. The README notes that since version 2.2.0 Swagger Core supports OpenAPI 3.1, and the compatibility table lists every 2.2.x release as 3.x compatible. If your consumers or gateway expect a specific revision, that table is the place to check before an upgrade, not the release notes alone.

## Getting started: the dependency and where the integration steps live

The README points to the wiki page "Swagger 2.X - Getting started" for setup, and the compatibility table lists 2.2.55 as the current stable release, dated 2026-08-31. The project is published to Maven Central under the group io.swagger.core.v3, which is what the RELATED SEARCHES phrase "swagger core maven dependency" refers to.

The README itself gives no sample resource class, no configuration snippet and no registration step. It says only that the getting-started guide is on the wiki. So the dependency coordinates are the one concrete thing the repository states directly, and the wiring for your JAX-RS implementation is something you read there. The README does not document a rollback procedure, so removing the integration later is a manual change on your side.

What you should expect once it is wired up is a served OpenAPI document describing your endpoints, derived from the annotations already on your resource classes. If you are on the jakarta namespace, the README states that the parallel artifacts carry a -jakarta suffix, so the artifactId you resolve will differ from the javax case.

## The javax and jakarta split is the first thing that will break a build

The most common failure mode is a namespace mismatch, and it fails at compile or startup time rather than quietly. The README is explicit that there are two parallel artifact sets, one unsuffixed for javax and one with the -jakarta suffix, and that both provide the same functionality. Pick the wrong one and the annotations your application actually uses will not be the annotations the library scans.

This is a real constraint, not a documentation quirk. A codebase partway through a jakarta migration has both namespaces present, and the library cannot paper over that. You either complete the migration first or you keep the javax artifacts until you do.

A second boundary is the framework. The README states that current version supports JAX-RS2. A Spring MVC application is not a JAX-RS2 application, and this repository's README does not claim to cover it. Teams sometimes assume that any Java REST framework will work because the annotations look similar. They do not, and the README's compatibility statement is the line to read before assuming otherwise.

## Where Swagger Core sits relative to SpringDoc and design-first tooling

The nearest alternative in the Java ecosystem is SpringDoc, which targets Spring Boot applications and derives an OpenAPI document from Spring MVC annotations. The difference in approach is the annotation vocabulary, not the output format. Both emit an OpenAPI document; one reads JAX-RS annotations, the other reads Spring annotations. If your service is Spring MVC, SpringDoc is the natural fit and Swagger Core is the wrong tool for the same reason a JAX-RS library would be.

A second alternative is the design-first route: write the OpenAPI document by hand in Swagger Editor, then generate server interfaces from it. That inverts the data flow. With Swagger Core the code is the source of truth and the document is a derived artifact. With design-first the document is the source of truth and the code is generated. Neither is strictly better; they fail differently. A derived document can drift only if the annotations are wrong, while a hand-written document can drift any time someone changes an endpoint and forgets to edit the YAML.

The RELATED SEARCHES list includes Swagger Editor and Swagger UI. Those are separate products in the same family. Swagger Core does not render anything and does not provide an editing surface; it produces the document those tools consume.

## Release cadence, licence and the cost of staying current

The compatibility table shows a dense release history. 2.2.55 shipped on 2026-08-31, 2.2.54 on 2026-08-18, and 2.2.53 on 2026-08-03. Earlier entries run back through 2024 and 2025 at a similar rhythm, with gaps of a few weeks to a few months. The last push to the repository was on 2026-09-21, and the repository is not archived.

That cadence is the upgrade cost. A library that publishes every two to four weeks means version bumps are cheap individually but constant, and each one is a chance for a transitive dependency to shift. The practical approach is to pin the version in your build and move deliberately rather than tracking the latest release. The 2.2.x line has stayed on OpenAPI 3.x throughout, so within that line the specification revision is not changing under you.

The licence is Apache-2.0, and the repository carries both a LICENSE and a NOTICE file at the top level. Apache-2.0 permits commercial use and modification and includes a patent grant; the NOTICE file is the mechanism for attribution when the work is redistributed. That is a description of what the licence text provides, not legal advice. If you redistribute the library inside a product, have someone who can read the licence confirm what your distribution requires.

## Choosing between the two Swagger Core artifact lines

The decision comes down to one question: which namespace does your application compile against? If it is javax, take the unsuffixed artifacts. If it is jakarta, take the -jakarta artifacts. The README states both provide the same functionality, so nothing else changes.

A second question is which OpenAPI revision your consumers accept. OpenAPI 3.1 support arrived in 2.2.0, so any 2.2.x release can emit it, but a gateway or code generator downstream may still expect an earlier revision. The compatibility table is the authoritative mapping between library version and specification revision, and it lists every 2.2.x release from 2.2.21 onward as 3.x compatible.

The thing to verify before committing is the getting-started path on the wiki, because the README does not carry the integration steps. That page is where the registration details for your JAX-RS implementation live, and it is the difference between a dependency that works and one that sits unused in your build file.

## Conclusion

Adopt Swagger Core if you have a JAX-RS service and want the OpenAPI document generated from the annotations you already write, rather than maintained by hand. Do not adopt it if you need a rendered API explorer, a design-first workflow, or Spring MVC support from this repository alone; it produces the specification document and stops there. Before wiring it in, verify which namespace your runtime uses (javax or jakarta), because the two artifact sets are separate, and check which OpenAPI revision your downstream tooling accepts, since 3.1 support only arrived in 2.2.0.

## FAQ

### What is Swagger Core used for?

It is a Java implementation of the OpenAPI Specification that generates an OpenAPI document from your JAX-RS2 annotated code. The README describes it as examples and server integrations for generating the Swagger API Specification.

### Is Swagger Core outdated?

No. The repository is not archived, the last push was on 2026-09-21, and the current stable release 2.2.55 shipped on 2026-08-31. The compatibility table lists every 2.2.x release as supported and OpenAPI 3.x compatible.

### What is replacing Swagger Core?

Nothing in this repository replaces it. Swagger Core targets JAX-RS2, so a Spring MVC service would use a Spring-oriented generator such as SpringDoc instead, but that is a different framework target rather than a successor to this library.

## Sources

- [License: Apache-2.0](https://github.com/swagger-api/swagger-core/blob/master/LICENSE)
- [Project website](http://swagger.io)
- [README](https://github.com/swagger-api/swagger-core/blob/master/README.md)
- [Releases](https://github.com/swagger-api/swagger-core/releases)
- [swagger-api/swagger-core on GitHub](https://github.com/swagger-api/swagger-core)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swagger-api-swagger-core