Swagger

Introduction

Swagger is a formal specification for a language-agnostic interface to REST APIs. This interface lets both humans and computers understand an API’s capabilities such that a consumer of the API can interact with the service. In simple terms, swagger is a JSON representation of a RESTful API, typically made available over HTTP at /swagger.json.

A simple swagger.json will look something like this.

{
    "swagger":"2.0",
    "info":{},
    "basePath":"/",
    "tags":[{"name":"time"}],
    "paths":{
        "/time/now":{
            "get":{
                "tags":["time"],
                "summary":"Get the current time",
                "description":"Returns the time as a string",
                "operationId":"get",
                "produces":["application/json"],
                "parameters":[],
                "responses":{
                    "200":{
                        "description":"successful operation",
                        "schema":{"type":"string"}
                    }
                }
            }
        }
    }
}

WildFly Swarm provides a swagger fraction that enables JAX-RS API developers to easily publish a /swagger.json describing the API.

To learn more about Swagger’s capabilities, see the Swagger website.

Configuration

To enable Swagger in your application, you need to add a dependency to your pom.xml.

<dependency>
  <groupId>org.wildfly.swarm</groupId>
  <artifactId>swagger</artifactId>
</dependency>

Usage

The swagger fraction pulls in required dependencies, and when your application is deployed, the underlying Swagger system is automatically configured and initialized.

By default, swagger can be used with zero-configuration. This means you can simply include the swagger fraction in the POM file for your application, and WildFly Swarm will figure out reasonable defaults. However, if you would like to customize the configuration, this is possible using ShrinkWrap and SwaggerArchive. Configure this in the main() method for your application.

    public static void main(String[] args) throws Exception {

        Swarm swarm = new Swarm();

        JAXRSArchive deployment = ShrinkWrap.create(JAXRSArchive.class, "swagger-app.war");
        deployment.addClass(TimeResource.class);

        // Enable the swagger bits
        SwaggerArchive archive = deployment.as(SwaggerArchive.class);
        // Tell swagger where our resources are
        archive.setResourcePackages("org.wildfly.swarm.examples");
        archive.setTitle("My Awesome Application");

        deployment.addAllDependencies();
        swarm
                .fraction(LoggingFraction.createDefaultLoggingFraction())
                .start()
                .deploy(deployment);
    }
}

The packages are recursively scanned, so if you have a package hierarchy, you just need to set the top level package name. See the SwaggerArchive interface for additional configuration options.

Usage with WAR packaging (META-INF/swarm.swagger.conf)

If you don’t use JAR packaging, like in the example above (no custom Main()), then you would need to configure swagger through META-INF/swarm.swagger.conf. It allows you to specify resource packages to be scanned and other atributes, similar to SwaggerArchive in the previous example.

packages:com.example.rest   (1)
root:rest                   (2)
title:WildFly Swarm Demo    (3)

  1. resource packages for the swagger annotation scanner (comma delimited, String[])

  2. the content root, which typically is configured in the jaxrs.Application

  3. arbitraty othe things to pimp up the UI appearance

Swagger UI

The folks over at http://swagger.io have also created an HTML5/JavaScript application for querying and interacting with swagger-enabled REST APIs. WildFly Swarm provides a simple way to deploy this application using the Swagger-UI server. See the Servers documentation for more information.