Swagger installing and configuration description

Swagger is a technology that allows documenting REST services. Swagger supports many programming languages and frameworks. Swagger also provides UI for documentation viewing.

In this article, I’ll tell you how to plug Swagger in to Maven project, where REST services are implemented using JAX-RS – RESTEasy specification. Connection of Swagger to the project, using documentation of REST services with the help of annotations, description of documentation visualization through Web UI will be written in the article.

First we need to add Swagger’s dependency to the Maven project. Since we will connect Swagger to RESTEasy, we will add the appropriate dependency.

<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jaxrs</artifactId>
<version>1.5.6</version>
</dependency>

At the time of writing the manual the current version is 1.5.6.

It should be considered, that Swagger has legacy Maven repository. Legacy repository has groupId=com.wordnik. You should take this into account and not to confuse dependencies!

For more information, follow the link.

Next, we have to add necessary listeners to the project, so that Swagger can automatically detect annotations and generate documentation.

We set up the project using a descendant class of javax.ws.rs.core.Application.

The setting will look like this:

public class SampleApplication extends Application {
@Override
public Set<Cass<?>> getClasses() {
    Set<Class<?>> resources = new HashSet();
    resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);
    resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);
    return resources;
    }
}

To read more about other adding methods, follow the link.

Next, it’s necessary to set configurations of Swagger itself. We did this in the constructor of the same Application class descendant.

public class SampleApplication extends Application {
public SampleApplication() {
 BeanConfig beanConfig = new BeanConfig();
  beanConfig.setVersion(“1.0.0”);
  beanConfig.setBasePath(“/api”);
  beanConfig.setResourcePackage(“org.jazzteam”);
  beanConfig.setScan(true);
}
@Override
public Set<Class<?>> getClasses() {
 Set<Class<?>> resources = new HashSet();
  resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);
  resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);
  return resources;
 }
}

To read more about other methods of configuration, follow the link.

After all the settings, information about the application should be available by the following link http://localhost:8080/api/swagger.json. It is also possible to output information in YAML format (for this you need to change JSON to YAML in the link).

For the beginning, I’ll describe the annotations that are necessary for correct documentation and correct displaying of REST services on Swagger-UI.

In order for Swagger to determine that there are REST services in the class, this class should be marked with the @Api annotation. In the parameters of this annotation you can specify the name of the section, where RESTs in UI will be, and specify the description of this section.

For example:

@Api(value = “Account”, description = “APIs for working with users”)
public class AccountRestService {…}

@ApiOperation annotation is necessary to be specified above the method of REST service. Also in its parameters, you can specify the description of service.

@Path("login")
@POST
@ApiOperation(value = "Login")
public Response login() {...}

For explicit indication of headers that are required for a particular service, you can use the annotation @ApiImplicitParam.

@Path(“logout”)
@POST
@ApiOperation(value = “Logout”)
@ApiImplicitParams({
    @ApiImplicitParam(name = “Authorization”, paramType = “header”,
      dataType = “string”,required = true,
      defaultValue = “Token <paste_token_here>”)
}) public Response logout() {…}

For explicit indication of the response object, you can use @ApiResponse annotation. It will be useful if REST returns the Response object as the answer from the server.

@Path(“login”)
@POST
@ApiOperation(value = “Login”)
@ApiResponses(value = {
     @ApiResponse(code = 200, message = “OK”, response = Token.class)
})
public Response login() {…}<

More detailed information about all the annotations you can find here.

For visualization, it is necessary to upload this project https://github.com/swagger-api/swagger-ui.

In the dist directory the index.html file will be located, we need to open it.

Next in the upper input field we need to enter the above mentioned url http://localhost:8080/api/swagger.json and click the Explore button.

To set the url by default it’s necessary to edit the source code of the index.html file.

After that, we’ll see the documentation of our REST services. We can make requests to REST services directly from UI.

If Swagger issues an error can’t fetch, we’ll have to configure the CORS headers in the server where our application is deployed, we need to add the Access-Control-Allow-Origin header:*

An example of display REST services on UI:

List of REST services on Web-UI:

The form of detailed information about REST service and the possibility of sending a request.