Category: swagger

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

itzap-jerseyswagger

itzap-jerseyswagger library is designed to provide swagger UI endpoint to the Jersey REST API application.

Usage

Include itzap-jerseyswagger dependency to your project.

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

add the following properties to the application config file

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

The following code will add swaggerUI artifacts and context

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

How To Build

  • Clone the following projects:
    • git clone git@github.com:avinokurov/itzap-parent.git
    • git clone git@github.com:avinokurov/itzap-common.git
  • Build all projects
    • cd itzap-parent && mvn clean install
    • cd ../itzap-common && mvn clean install

Visit my ITZap blog to read more about this project.

Code

Complete implementation can be found here: