In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See here for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup. I am using Swagger 1.5, Maven 3.3.3, Jersey 1.8, and Jetty 7.3. Make sure you add all dependencies to your pom.xml.

In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

1. Add the package scanning packages to your servlets which will serve your REST API. {add-package-scanning}
2. Add the Swagger package scanning servlet. {add-swagger-servlet}
3. [Optional] Package the Swagger-UI static HTML5 content with your server {add-swagger-ui}

Let's start with a basic server class, adapted from the Eclipse tutorial above.

public class MyServer {
  public static void main(String[] args) throws Exception
  {
      Server server = new Server(8080);
      ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
      context.setContextPath("/");
      server.setHandler(context);
      
      ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
      apiServlet.setInitOrder(1);
      apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources");
      
      server.start();
      server.join();
  }
}

Our package setup is very minimal:

• src
  • main
    • java
      • MyServer.java
    • resources

In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like so:

ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like this. In your embedded Jetty servlet setup, you are setting the packages you are serving via the "com.sun.jersey.config.property.packages" property. So, add the io.swagger.jaxrs.json;io.swagger.jaxrs.listing packages to your servlet setup, like so:

public class MyServer {
  public static void main(String[] args) throws Exception
  {
      Server server = new Server(8080);
      ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
      context.setContextPath("/");
      server.setHandler(context);
      
      ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
      apiServlet.setInitOrder(1);
      apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");
      
      server.start();
      server.join();
  }
}

Now, to configure and initialize Swagger. Based on these instructions, you'll now manually create and add the Swagger servlet. The path provided for the Swagger servlet is irrelevant, as it is not actually accessed through this path. However, make sure it does not collide with any of your other resource paths!

public class MyServer {
  public static void main(String[] args) throws Exception
  {
      Server server = new Server(8080);
      ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
      context.setContextPath("/");
      server.setHandler(context);
      
      ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
      apiServlet.setInitOrder(1);
      apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");
      
      ServletHolder swaggerServlet = context.addServlet(DefaultJaxrsConfig.class, "/swagger-core");
      swaggerServlet.setInitOrder(2);
      swaggerServlet.setInitParameter("api.version", "1.0.0");
    
      server.start();
      server.join();
  }
}

Now, when you navigate to http://<host>:<port>/api/swagger.json, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses. However, most people prefer a more human readable method -- so we will now package the Swagger-UI HTML5 project with your server.

To your pom.xml, you need to add the ability to download and