Swagger quickstart tutorial

Swagger is a popular specification for REST APIs which can be used for a variety of purposes such as:

  • Generating an interactive API console to quickly learn about and try the API.
  • Generating the client SDK code needed for implementations on various platforms.

In order to integrate Swagger with your Web application you need to following three steps:

  • You need to marge the User Interface components from swagger-ui project
  • Apply the Swagger API annotations in your REST Service
  • Bootstrap Swagger in your Web server

Merging Swagger UI in your Web project

The Swagger UI Project is available at the following URL: https://github.com/swagger-api/swagger-ui

What you need to do in a nutshell is copying the content of the dist folder of swagger-ui into your project's webapp folder. Once done with it, pick up the welcome page, named index.html and edit the file to specify the url of your Swagger service, for example:

      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://localhost:8080/swagger-demo/api/swagger.json";
      }

Applying Swagger API annotations

Done with merging your UserInterface let's move to the REST Service.

package com.mastertheboss;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/simple")
@Api(value = "SimpleRESTService", description = "Swagger Demo")
public class SimpleRESTService {
	@GET
	@Path("/text")
	@ApiOperation(value = "Hello World Swagger")
	public String getHello () 
	{
		return "hello world!";
	} 
	@GET
	@Path("/json")
	@ApiOperation(value = "Returns param", notes = "Returns param", response = SimpleProperty.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful retrieval of param value", response = SimpleProperty.class)})
	@Produces(MediaType.APPLICATION_JSON)
	public SimpleProperty getPropertyJSON () 
	{
        SimpleProperty p = new SimpleProperty("key","value");
		return p;
	}
	@GET
	@Path("/xml")
 
	@ApiOperation(value = "Returns param", notes = "Returns param", response = SimpleProperty.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful retrieval of param value", response = SimpleProperty.class)})
	@Produces(MediaType.APPLICATION_XML)
	public SimpleProperty getPropertyXML () 
	{
        SimpleProperty p = new SimpleProperty("key","value");
		return p;
	}
}

Aside from standard JAX-RS annotations, two Swagger core annotations have been included in your REST Service:

  • @io.swagger.annotations.Api Which marks a class as a Swagger resource. By default, Swagger-Core will only include and introspect only classes that are annotated with @Api and will ignore other resources
  • @io.swagger.annotations.ApiOperation Which describes an operation or typically a HTTP method against a specific path.

Finally you need to bootstrap Swagger core engine in order to be able to run its Api. For the sake of simplicity, we will use the Application class to bootstrap your Swagger core. If you need an higher level of flexibility we suggest having a look at the Spring configuration at the following link: https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-RESTEasy-2.X-Project-Setup

package com.mastertheboss;

import io.swagger.jaxrs.config.BeanConfig;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
 

@ApplicationPath("/api")
public class Configurator extends Application {

 
    public Configurator() {
        init();
    }
 

    private void init() {
      
    	  BeanConfig beanConfig = new BeanConfig();
          beanConfig.setVersion("1.0.0");
          beanConfig.setSchemes(new String[]{"http"});
          beanConfig.setHost("localhost:8080");
          beanConfig.setBasePath("/swagger-demo/api");
          beanConfig.setResourcePackage(SimpleRESTService.class.getPackage().getName());
          beanConfig.setTitle("RESTEasy, Swagger and Swagger UI Example");
          beanConfig.setDescription("Sample RESTful API built using RESTEasy, Swagger and Swagger UI");
          beanConfig.setScan(true);
    }
}

That's all. Now build and deploy your Web application on WildFly and surf on the home page of it. As you can see from the following picture an interactive API console is available for every operation:

Swagger quickstart tutorial

If you expand each operation you will be able to learn more about it and eventually test the operation:

Swagger quickstart tutorial

You can checkout for the source code of this example at: https://github.com/fmarchioni/mastertheboss/tree/master/swagger-demo

Follow us on Twitter