Repository navigation
Swagger 3.X Getting started
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.
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. Swagger Core 3.0 is not compatible with Jackson 2. - Only the
jakarta.*namespace is supported. - The Jakarta REST module
swagger-jaxrs2is nowswagger-rest, and its packages and some types were renamed.
All of these changes, with before / after examples, are listed in Migration to 3.0.
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.
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.
The definition can also be resolved at build time with a plugin:
-
swagger-maven-plugin(io.swagger.core.v3:swagger-maven-plugin:3.0.0; in 3.0 there is no-jakartavariant). See the module readme. -
swagger-gradle-plugin(plugin idio.swagger.core.v3.swagger-gradle-plugin, version3.0.0; needs a Gradle version compatible with Java 17+). See the module readme.
Both use the same resolving and configuration mechanisms as the runtime integration, so most of the documentation applies to both.
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.
- 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
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.
Consider a simple application with a resource like this (3.0, jakarta.ws.rs):
import io.swagger.v3.oas.annotations.Parameter;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Response;
@Path("/pet")
@Produces({"application/json"})
public class PetResource {
@GET
@Path("/{petId}")
public Pet getPetById(@PathParam("petId") Long petId) {
// return pet
return new Pet();
}
@POST
@Consumes("application/json")
public Response addPet(
@Parameter(description = "Pet object that needs to be added to the store", required = true) Pet pet) {
// add pet
return Response.ok().entity("SUCCESS").build();
}
}and a model class:
import java.util.ArrayList;
import java.util.List;
public class Pet {
private long id;
private String name;
private List<Tag> tags = new ArrayList<>();
public long getId() { return id; }
public void setId(long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public List<Tag> getTags() { return tags; }
public void setTags(List<Tag> tags) { this.tags = tags; }
}The annotations, the resolved definition and everything else work as described in the 2.X quick start, which also shows the resolved result. Note that the 2.X example uses javax.ws.rs imports and JAXB annotations; in 3.0 use jakarta.ws.rs.
Continue with the 2.X pages, applying the renames: