Skip to content

Swagger 3.X Getting started

Daniel Kmiecik edited this page Oct 15, 2026 · 2 revisions

NOTE: Swagger Core 3.0 produces OpenAPI 3.0 and 3.1 definition files. If you are looking for Swagger Core 2.X, please refer to 2.X Getting started.


What is it about?

swagger-core is an open source Java implementation of Swagger/OpenAPI. Release 3.0 is a major release, but it does not change how Swagger Core works: annotations, configuration, resource scanning, the Reader, filters and extension points behave as they did in 2.X.

What changed is the platform and the names:

  • Java 17+ is required.
  • Jackson 3 (tools.jackson) replaces Jackson 2.
  • Only the jakarta.* namespace is supported.
  • The Jakarta REST module swagger-jaxrs2 is now swagger-rest, and its packages and some types were renamed.

All of these changes, with before / after examples, are listed in Migration to 3.0.

Use the 2.X documentation

Because the behaviour is the same, this wiki's 2.X pages are the reference for 3.0 too. Read them as usual, and apply the changes from Migration to 3.0 wherever you see a name that changed.

When a 2.X page mentions... In 3.0 use... Details
swagger-jaxrs2, swagger-*-jakarta artifacts, -v2 servlet initializer swagger-rest, swagger-core, swagger-rest-servlet-initializer, ... (version 3.0.0) Artifacts
io.swagger.v3.jaxrs2.* packages io.swagger.v3.rest.* Packages and types
JaxrsOpenApiContextBuilder, Jaxrs*Scanner, ... RestOpenApiContextBuilder, Rest*Scanner, ... Renamed types
javax.*, "Jakarta namespace support" notes jakarta.* only, nothing to switch Jakarta REST and Servlet APIs
Jackson classes in ObjectMapperProcessor, custom resolvers, serializers Jackson 3 (tools.jackson) APIs Jackson 3 changes
JSON / YAML output, property names, date and Month values Jackson 3 defaults Mapper defaults

Everything not covered by the table (annotations, configuration properties, scanning, Reader listeners, filters, OpenAPI 3.1 support) is unchanged.

Where to start

The most common usage scenario is to integrate swagger-rest into an existing or new Jakarta REST project (code-first), to automatically provide and expose its API definition, kept in sync during the project lifecycle. That definition can feed API documentation (for example swagger-ui), client generation (for example swagger-codegen), and custom processing.

Starting a new project? Follow the Quick start below, then continue with Integration and configuration and Annotations, applying the renames above.

Upgrading an existing project? Start with Migration to 3.0, in particular Before you start and the migration steps.

Requirements

  • Java 17+
  • Jakarta REST (jakarta.ws.rs-api) 4.0.0 and Jakarta Servlet (jakarta.servlet-api) 6.1.0, from a Jakarta EE 11 compatible container or libraries

Quick start

Swagger artifacts are available on Maven Central, so they work with any dependency management system that supports Maven dependencies (Maven, Ivy, Gradle). Without Maven, see Not using Maven.

For a Jakarta REST application, add the dependencies to the project POM:

  <dependencies>
    ...
    <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-rest</artifactId>
      <version>3.0.0</version>
    </dependency>
    <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-rest-servlet-initializer</artifactId>
      <version>3.0.0</version>
    </dependency>
  </dependencies>

or in Gradle (Kotlin DSL):

implementation("io.swagger.core.v3:swagger-rest:3.0.0")
implementation("io.swagger.core.v3:swagger-rest-servlet-initializer:3.0.0")

To keep all Swagger artifacts on the same version, import the BOM io.swagger.core.v3:swagger-bom and omit the versions.

Just by adding the dependencies, an endpoint <server_url>/<application_path>/openapi.json (and openapi.yaml) is activated, exposing the OpenAPI definition of your application, resolved from its Jakarta REST resources. The endpoint is fully configurable; see Integration and configuration.

The resources and the resulting definition are the same as in 2.X, apart from the jakarta.ws.rs imports. See the 2.X quick start for a complete resource example and the resolved result.

Dig deeper

Continue with the 2.X pages, applying the renames:

Clone this wiki locally