Integrate OpenAPI with Jetty


Jetty 11.X is now released and has deprecated its support for javax namespace required for the development of API. Instead, it has started supporting jakarta namespace which is part of Jakarta EE 9 and this changes the game entirely. When you need to annotate your API, we import* packages which are now on will be import*.

What is Jetty?

The Ecplise Jetty Project provides a web server and servlet container, additionally providing support for HTTP/2, WebSocket, OSGi, JMX, JNDI, JAAS, and many other integrations. These components are open source and are freely available for commercial use and distribution.

What is Jersey?

According to Wikipedia, Jersey RESTful Web Services, formerly Glassfish Jersey, currently Eclipse Jersey framework is an open-source framework for developing RESTful Web Services in Java. It provides support for JAX-RS APIs and serves as a JAX-RS (JSR 311 & JSR 339 & JSR 370) Reference Implementation.

  • Provide APIs to extend Jersey & Build a community of users and developers, and finally
  • Make it easy to build RESTful Web services utilizing Java and the Java Virtual Machine.

What is Swagger/OpenAPI?

Swagger is an open-source set of rules, specifications, and tools for developing and describing RESTful APIs. The Swagger framework allows developers to create interactive, machine, and human-readable API documentation.

What steps it should follow?

The rules are very simple and as follows:

STEP 1. Create Jetty Server

The general idea here is to create a jetty server instance, add contextHandler for the API on a particular path such as /sampleapi below and start the server.

// Create and configure a ThreadPool.
QueuedThreadPool threadPool = new QueuedThreadPool();
// Create a Server instance.
Server server = new Server(threadPool);
// HTTP configuration and connection factory.
HttpConfiguration httpConfig = new HttpConfiguration();HttpConnectionFactory http11 = new HttpConnectionFactory(httpConfig);
// Create a ServerConnector to accept connections from clients.
ServerConnector connector = new ServerConnector(server, 1, 1, http11);
// Create ContextHandlerCollection context
ContextHandlerCollection contexts = new ContextHandlerCollection();
// Adding server path for API
ContextHandler sampleApiHandler = new ContextHandler(“/sampleapi”);
sampleApiHandler.setHandler(new SampleApiHandler());

STEP 2. Intercept API using Jersey

Extending the ContextHandler for server, now let's add Jersey servlet to intercept the REST API you have developed. Package jersey.config.server.provider.packages is the key and the value com.example.sample-package holds all your APIs. Additional resources that need to be scanned can also be specified in the value section as below -

// Setup Jetty Servlet
ServletContextHandler servletContextHandler = new ServletContextHandler(ServletContextHandler.SESSIONS);
// Setup API resources to be intercepted by Jersey
ServletHolder jersey = servletContextHandler.addServlet(ServletContainer.class, “/api/*”);
“com.example.sample-package; io.swagger.v3.jaxrs2.integration.resources”);
@OpenAPIDefinition(info = @Info(
title = “MyTitle”,
version = “1.0.0”,
description = “API Documentation”,
license = @License(name = “Test License”, url = “"),
contact = @Contact(url = “")))
public class SampleApiClass extends AbstractHandler {
summary = “SampleApi”, description = “returns a list of clients”)
@ApiResponse(content = @Content(mediaType = “application/json”))
@ApiResponse(responseCode = “200”, description = “Ok”)
@ApiResponse(responseCode = “400”, description = “Bad Request”)
@ApiResponse(responseCode = “404”, description = “Error”)
@ApiResponse(responseCode = “500”, description = “Internal Server Error”)
@ApiResponse(responseCode = “503”, description = “Service Unavailable”)
@Tag(name = “MyApi”)
public void SampleApi(@Context Request jettyRequest, @Context HttpServletRequest request, @Context HttpServletResponse response) {…}

STEP 3. Add OpenAPI servlet into Jetty Server

Let’s now add an OpenAPI servlet into the server context on a separate path /openapi so that we would be able to generate API docs independently when the serer is running. Also, this will allow us to download and save the docs as YAML or JSON.

// Expose API definition independently into yaml/json
ServletHolder openApi = servletContextHandler.addServlet(OpenApiServlet.class, “/openapi/*”);
openApi.setInitParameter(“openApi.configuration.resourcePackages”, “com.example.sample-package”);

STEP 4. Add static-UI pages into /resources/webapp

Let's try to make it more human-readable. Swagger-UI package holds a directory /dist/ which contains the html package to build a static UI page. You need to go to swagger-UI Github and copy the content of dist/ into /resources/webapp of your project directory. You may require to change the value of the source in index.html to http://localhost:8080/openapi/swagger.json. This will create a hook between static resources to your swagger.json. And finally, add resourceBasePath for this to work as below -

// Setup Swagger-UI static resources
String resourceBasePath = ServiceLoader.class.getResource(“/webapp”).toExternalForm();
servletContextHandler.setWelcomeFiles(new String[] {“index.html”});
servletContextHandler.addServlet(new ServletHolder(new DefaultServlet()), “/*”);
// Start the Server so it starts accepting connections from clients.
dependencies {
implementation ‘org.eclipse.jetty:jetty-server:11.0.0’
implementation ‘org.eclipse.jetty:jetty-util:11.0.0’
implementation ‘org.eclipse.jetty:jetty-servlet:11.0.0’
// Jersey dependencies
implementation ‘org.glassfish.jersey.containers:jersey-container- jetty-http:3.0.2’
implementation ‘org.glassfish.jersey.containers:jersey-container-servlet-core:3.0.2’
implementation ‘’
implementation ‘org.glassfish.jersey.core:jersey-common:3.0.2’
implementation ‘org.glassfish.jersey.inject:jersey-hk2:3.0.2’
implementation ‘org.glassfish.jaxb:jaxb-runtime:3.0.1’
// Swagger & Jakarta namespace dependencies
implementation ‘org.apache.commons:commons-lang3:3.7’
implementation ‘io.swagger.core.v3:swagger-jaxrs2-jakarta:2.1.9’
implementation ‘io.swagger.core.v3:swagger-jaxrs2-servlet-initializer-jakarta:2.1.9’
implementation ‘’
implementation ‘jakarta.servlet:jakarta.servlet-api:5.0.0’

STEP 5. Export API docs

If you are willing to export all your docs to share with others in your team or at your workplace, you can go to the URL http://localhost:8080/openapi/openapi.yaml or http://localhost:8080/openapi/openapi.json to export the docs as YAML or JSON file respectively.

Further Scope

The saved YAML or JSON documentation can be used to exercise the APIs into tools like the postman. Also, If you want to generate client SDK using docs, you can use the `swagger-generate` tool in your favorite language like this -

swagger-generate -i <openapi.yaml-OR-running-server-URL> -l <language-of-choice> -o <output-directory>
swagger-generate -i http://localhost:8080/openapi/openapi.yaml -l python -o /tmp/sdk-client-python


If you are working with Jetty 11 and developing REST Apis, you tend to require your API documentation. OpenAPi is the most standard specification that can be followed for API development and is popularly accepted in the industry today. All you need to do is — import dependencies in the dependency tool, annotate code with OAS standards, hook up jersey and swagger into Jetty and enjoy using API docs.

Super interested in Computer Science & Software Engineering with focus on AI, ML, Kubernetes