I remembered having used a cool framework for self-documenting APIs called Swagger on a recent contract I was working on. Swagger is brilliant, easy and intuitive. Or so I thought.

What should have been a simple “point-click-run” in my head, turned out to be a bit more painful. I couldn’t find a Swagger example where there was no Spring MVC or web.xml dependencies. I just wanted it to run in a self-contained JAR using embedded Jetty – a clean package that runs anywhere. I found several examples using Spring, and it seemed excessive. I don’t want Spring. There were several using web.xml. I don’t want to configure an XML. I just want to write Jersey APIs and have them just run.

After running through several examples here (Which are useful, just not for me), here (Though I didn’t really know what was happening…) and here, I finally gave up and went to the Swagger IRC channel on freenode. I found ron and tonytam really helpful in fixing my problems.

To set up Swagger, you need to do the following:

  1. Annotate your Jersey resources with Swagger annotations. This page here should get you started.
  2. Copy the contents of the dist folder from here to a folder called webapp in your resources folder.
    Swagger UI
  3. Add the following code to somewhere in your application, ensuring it runs during start up (Main method is a great place). This sets up Swagger’s info and code scanning.
    ` BeanConfig beanConfig = new BeanConfig();
    beanConfig.setVersion(“1.0.0”);
    beanConfig.setResourcePackage(ResourceClass.class.getPackage().getName());
    beanConfig.setScan(true);
    beanConfig.setBasePath(“/”);
    beanConfig.setDescription(“Description goes here”);
    beanConfig.setTitle(“Topic goes here”);
    `
    Replace ResourceClass.class with your Jersey Resource class.
  4. Add your resources and the Swagger JAX-RS resources to Jetty. This serves up your APIs and the swagger.json file that the Swagger UI uses.
    ` ResourceConfig resourceConfig = new ResourceConfig();
    resourceConfig.packages(ResourceClass.class.getPackage().getName(), “com.wordnik.swagger.jaxrs.listing”);
    ServletContainer servletContainer = new ServletContainer(resourceConfig);
    ServletHolder entityBrowser = new ServletHolder(servletContainer);
    ServletContextHandler entityBrowserContext = new ServletContextHandler(ServletContextHandler.SESSIONS);
    entityBrowserContext.setContextPath(“/”);
    entityBrowserContext.addServlet(entityBrowser, “/*”);
    `
    Replace ResourceClass.class with your Jersey Resource class. com.wordnik.swagger.jaxrs.listing loads up Swagger’s resources, namely com.wordnik.swagger.jaxrs.listing.ApiListingResource and com.wordnik.swagger.jaxrs.listing.SwaggerSerializers. Add this entityBrowserContext to your Jetty server.
    This should now serve up http://localhost:9999/swagger.json

Start your application using the main class, and everything should work as planned. You should see this when you open http://localhost:9999/docs:
Swagger UI

TL;DR
I get annoyed when I have to read a lot of text for something I want quick. I also hate it when there are no code samples that I can run, and dependencies aren’t mentioned correctly and all that stuff. So here you go:
Get my Github repository from here.
Follow the readme.md and look at the code, which should get you started on how to set up a Spring/web.xml free Jersey2 and Swagger on embedded Jetty!