Spring Boot: Setup Swagger to Document Your REST Resources

How-to: Spring Boot- Setup Swagger to document your REST resources

These instructions assume you have a base Spring Boot project installed with a JAX-RS endpoint functioning correctly. If you do not have this, feel free to see these previous post for setting this up.

Setting up base JAX-RS Spring Boot project

Setting up your Jersey Configuration and first REST endpoint

Step 1: Add the dependency to your POM file

Add the following dependency to your project pom.xml file.

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>1.5.6</version>
</dependency>
Step 2: Setup your Swagger Configuration class

Add a SwaggerConfig class to your project and call setResourcePackage to point to the base package that will contain your resources.

import io.swagger.jaxrs.config.BeanConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig{

    @Bean
    public BeanConfig swaggerConfiguration() {
        final BeanConfig beanConfig = new BeanConfig();
        beanConfig.setResourcePackage("com.familyassist.messaging.resources");
        beanConfig.setScan(true);
        beanConfig.setPrettyPrint(true);
        return beanConfig;
    }
}
Step 3: Change your Jersey Configuration to add the Swagger serializers

In your resource configuration, add two lines of code to register the Swagger REST resource and to register the Swagger Serializer class.

import org.glassfish.jersey.server.ResourceConfig;
import org.springframework.stereotype.Component;

@Component
public class JerseyResourceConfig extends ResourceConfig {

    public JerseyResourceConfig() {
        /* Set package to scan for application Resources/Endpoints */
         packages( "com.familyassist.messaging.resources;");
         register(io.swagger.jaxrs.listing.ApiListingResource.class);
         register(io.swagger.jaxrs.listing.SwaggerSerializers.class);

    }
}

Step 4: Change your previously created resource to add Swagger annotations
package com.familyassist.messaging.resources;

import io.swagger.annotations.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Slf4j
@Component
@Path("/messages")
@Api(value = "/messages",
        description = "will provide access to message resources. " +
                "These message resources provide the basis " +
                "for all of family assist communication.")
public class MessagingResource {

    @GET
    @Path("/")
    @ApiOperation(value = "Retrieve messages", 
                  notes="Retrieve messages from the family assist product forums.")
    @ApiResponses(value = {
            @ApiResponse(code = 200, 
                  message = "Successful retrieval of message ", 
                  response = String.class),
            @ApiResponse(code = 404, message = "Messages not found"),
            @ApiResponse(code = 500, message = "Internal server error")}
    )
    public String retrieveMessages() {
        return "fake message here";
    }

    @GET
    @Path("/{message-id}")
    @ApiOperation(value="Retrieve a message by id",
                  notes = "Retrieve a message by id from the family assist product forums.")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful retrieval of message ", 
                         response = String.class),
            @ApiResponse(code = 404, message = "Message not found for give ID"),
            @ApiResponse(code = 500, message = "Internal server error")}
    )
    public String retrieveMessage(@ApiParam(name = "message-id", 
                                            value = "ID for given message", 
                                            required = true) 
                                  @PathParam("message-id") String id) {
        return "fake message here";
    }
}

Start up your application to try it out. Once it is running, see if you can access the swagger.json. If the json is available, you are all set.

http://localhost:8080/swagger.json

Leave a Reply