Vision Statement

Provide a library that can serve swagger UI in Jersey application. Inspiration for this library was the SpringFox Swagger UI project that works with spring boot application.

Use Case

Suppose you have a runnable Jar Jersey REST API application with Open API annotations and would like to provide a swagger UI for API consumers to learn and play with your APIs. Swagger UI comes as a set of static Javascript files that need to be included in your application. In addition, you need to configure a web context that will serve swagger UI pages. By including itzap-jerseyswagger.jar in your project you will get an endpoint that will load functional Swagger UI with your API definitions.

Implementation Details

Here is the code that starts embedded Tomcat in the project that I described in my previous post itzap-message. I modified it to use Open API annotations and include swagger UI.

private static void start() throws Exception {

        String contextPath = "";
        String appBase = ".";
        String port = System.getenv("PORT");
        if (port == null || port.isEmpty()) {
            port = "8025";
        }

        Tomcat tomcat = new Tomcat();
        tomcat.setPort(Integer.parseInt(port));
        tomcat.getHost().setAppBase(appBase);

        Context context = tomcat.addWebapp(contextPath, appBase);

        Tomcat.addServlet(context, "jersey-container-servlet",
                new ServletContainer(resourceConfig()));
        context.addServletMappingDecoded(UDecoder.URLDecode("/v1/itzap/message/*", Charset.defaultCharset()),
                "jersey-container-servlet");

        SwaggerContext.addSwaggerServlet(tomcat, context,
                ConfigBuilder.builder(ConfigType.TYPE_SAFE)
                        .build()
                        .getConfig("swagger"),
                EmailApplication.class);

        tomcat.getConnector();
        tomcat.start();
        tomcat.getServer().await();
    }

The code to notice here is:

SwaggerContext.addSwaggerServlet(tomcat, context,
                ConfigBuilder.builder(ConfigType.TYPE_SAFE)
                        .build()
                        .getConfig("swagger"),
                EmailApplication.class);

That all you need to do to add swagger UI to the REST API application.

There are a few properties that need to be added to the project configuration.

swagger.package="com.itzap"
swagger.apiBaseUrl="http://${email.host}/v1/itzap/message/"

Now you can start the project java -jar message-impl/target/message-impl-0.0.1-SNAPSHOT.jar and navigate your browser to

http://localhost:8025/api/v1/swagger

Readme

<dependency>
    <groupId>com.itzap</groupId>
    <artifactId>itzap-jerseyswagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

swagger.package="com.itzap"
swagger.apiBaseUrl="http://${email.host}/v1/itzap/message/"

SwaggerContext.addSwaggerServlet(tomcat, context,
        ConfigBuilder.builder(ConfigType.TYPE_SAFE)
                .build()
                .getConfig("swagger"),
        EmailApplication.class);

Code

Complete implementation can be found here: