Jen-Ming Chung

Integrating Swagger into JAX-RS with Java EE 6 specification

Swagger is an awesome framework we often used to describe, consume and visualize our RESTful web services. Typically, we use Tomcat with Jersey as a servlet, then specify the Swagger package and Swagger Configuration class into web.xml, finally annotate the resources, methods and models to complete the configurations. Our team recently built a Java EE 7 application for a RESTful web service. The goal of this article is to share our experiences of configuring Swagger in Glassfish 4 without a web.xml.

Create Maven Enterprise Application

First of all, we create a new project through Maven Enterprise Application project template contains EAR, EJB and Web App archetypes call swagger4javaee.

NetBeans 7.4

Add Swagger-JAXRS Dependency

Adds a jaxrs-dependent swagger module for JAX-RS in swagger4javaee-web/pom.xml.


Specify a Swagger Configuration Class

We created a Java class called SwaggerJaxrsConfig in the package mainly refer to the lucasweble’s post on stackoverflow. Then we can configure the ApiVersion and BasePath for Swagger.



import com.wordnik.swagger.config.ConfigFactory;
import com.wordnik.swagger.config.ScannerFactory;
import com.wordnik.swagger.config.SwaggerConfig;
import com.wordnik.swagger.jaxrs.config.DefaultJaxrsScanner;
import com.wordnik.swagger.jaxrs.reader.DefaultJaxrsApiReader;
import com.wordnik.swagger.reader.ClassReaders;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;

@WebServlet(name = "SwaggerJaxrsConfig", loadOnStartup = 1)
public class SwaggerJaxrsConfig extends HttpServlet {

    public void init(ServletConfig servletConfig) {
        try {
            SwaggerConfig swaggerConfig = new SwaggerConfig();
            ScannerFactory.setScanner(new DefaultJaxrsScanner());
            ClassReaders.setReader(new DefaultJaxrsApiReader());
        } catch (ServletException e) {

Annotate REST resources

In the following example, a class named HelloResource is defined by producing JSON outputs by HTTP GET method. Moreover, we add stateless session beans functionalities by additional @Stateless annotation to leverage some advantages such as Injection.



import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiResponse;
import com.wordnik.swagger.annotations.ApiResponses;
import javax.ejb.Stateless;
import javax.json.Json;
import javax.json.JsonObject;
import javax.persistence.criteria.Order;

@Api(value = "/hello", description = "Say Hello!")
public class HelloResource {

    @ApiOperation(value = "Say Hello World",
            notes = "Anything Else?")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "OK"),
        @ApiResponse(code = 500, message = "Something wrong in Server")})
    public Response sayHello() {
        JsonObject value = Json.createObjectBuilder()
                .add("firstName", "Jeremy")
                .add("lastName", "Chung")
                .add("message", "Hello World!")
        return Response.status(200).entity(value).build();

Specify the swagger package

Add the following class in ApplicationConfig let JAX-RS can respond to requests for the Resource Listing and Api Declaration.



import java.util.Set;
public class ApplicationConfig extends Application {

    public Set<Class<?>> getClasses() {
        Set<Class<?>> resources = new java.util.HashSet<>();
        return resources;

     * Do not modify addRestResourceClasses() method.
     * It is automatically populated with
     * all resources defined in the project.
     * If required, comment out calling this method in getClasses().
    private void addRestResourceClasses(Set<Class<?>> resources) {

Test our configuration

After Clean and Build our project, deploying the EAR to the Glassfish 4.0, we can view our resource listing here, http://localhost:8080/swagger4javaee-web/rest/api-docs:

  "apiVersion": "1.0.0",
  "swaggerVersion": "1.2",
  "apis": [
      "path": "\/hello",
      "description": "Say Hello!"

and any subsequent api declarations such as /hello and the JSON description for the corresponding url http://localhost:8080/swagger4javaee-web/rest/api-docs/hello:

  "apiVersion": "1.0.0",
  "swaggerVersion": "1.2",
  "basePath": "http:\/\/localhost:8080\/swagger4javaee-web\/rest",
  "resourcePath": "\/hello",
  "apis": [
      "path": "\/hello",
      "operations": [
          "method": "GET",
          "summary": "Say Hello World",
          "notes": "Anything Else?",
          "type": "void",
          "nickname": "sayHello",
          "produces": [
          "parameters": [
          "responseMessages": [
              "code": 200,
              "message": "OK"
              "code": 500,
              "message": "Something wrong in Server"

Supports Cross-Domain Request

In order to support the cross-domain request (e.g., jQuery) for our REST web services, we can easily achieve it by utilising Filter to set access control on ServletResponse Header.


import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletResponse;

@WebFilter(filterName = "HTML5CorsFilter", urlPatterns = {"/rest/*"})
public class HTML5CorsFilter implements javax.servlet.Filter {

    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletResponse res = (HttpServletResponse) response;
        res.addHeader("Access-Control-Allow-Origin", "*");
        res.addHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
        res.addHeader("Access-Control-Allow-Headers", "Content-Type");
        chain.doFilter(request, response);

    public void init(FilterConfig filterConfig) throws ServletException {

    public void destroy() {


Supports Cross-Domain Requests

Integrate with Swagger UI

Here we leverage the Swagger UI to produce, visualize and consume our RESTful services. First, we clone the project via git clone As shown below, we can found a dist folder which contains the pre-built files.

Swagger UI - dist

Then copy all the pre-built files in dist folder and paste to the webapp folder (i.e., swagger4javaee/swagger4javaee-web/src/main/webapp) in our web project.

Swagger UI - Copy dist - Paste to webapp

Please note that we need to modify the url for api-docs in index.html, the value will be http://localhost:8080/swagger4javaee-web/rest/api-docs in this example.

Swagger UI - Set Url

Finally, let’s check the api-docs on http://localhost:8080/swagger4javaee-web/ and consume the hello REST service you’ll get the results as shown in the following figure.

Supports Cross-Domain Requests

Download Source Code

git clone