Integrating Swagger 2.0 with Spring Boot Using Springfox

IBM VP Angel Diaz highlighted that Swagger has become the de‑facto way to describe REST APIs; version 2.0 adds extensibility, a large community, and an emerging OpenAPI governance model under the Linux Foundation.

Swagger’s biggest advantage is the ability to generate documentation directly from Java source code using annotations, keeping the docs synchronized with the implementation.

IBM uses Swagger internally for many products, and the IBM Bluemix API Management service can import Swagger 2.0 definitions to manage APIs.

To bring Swagger into a Spring Boot project, the author chose Springfox, which integrates Swagger annotations with the Spring ecosystem without being part of the core Swagger libraries.

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>org.springframework</groupId> <artifactId>gs-rest-service</artifactId> <version>0.1.0</version> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.3.0.RELEASE</version> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> <scope>compile</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> <scope>compile</scope> </dependency> </dependencies> <properties> <java.version>1.8</java.version> </properties> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>

After adding the dependencies, Swagger is enabled in the main application class with @EnableSwagger2 and a Docket bean that configures the API group, information, and path selection.

package hello; import static springfox.documentation.builders.PathSelectors.regex; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import com.google.common.base.Predicate; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication @EnableSwagger2 @ComponentScan("hello") public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } @Bean public Docket newsApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("greetings") .apiInfo(apiInfo()) .select() .paths(regex("/greeting.*")) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring REST Sample with Swagger") .description("Spring REST Sample with Swagger") .termsOfServiceUrl("http://www-03.ibm.com/software/sla/sladb.nsf/sla/bm?Open") .contact("Niklas Heidloff") .license("Apache License Version 2.0") .licenseUrl("https://github.com/IBM-Bluemix/news-aggregator/blob/master/LICENSE") .version("2.0") .build(); } }

The controller is annotated with Swagger annotations to describe the operation, query parameter, and possible HTTP responses.

package hello; import java.util.concurrent.atomic.AtomicLong; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; @RestController public class GreetingController { private static final String template = "Hello, %s!"; private final AtomicLong counter = new AtomicLong(); @ApiOperation(value = "getGreeting", nickname = "getGreeting") @RequestMapping(method = RequestMethod.GET, path = "/greeting", produces = "application/json") @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "User's name", required = false, dataType = "string", paramType = "query", defaultValue = "Niklas") }) @ApiResponses(value = { @ApiResponse(code = 200, message = "Success", response = Greeting.class), @ApiResponse(code = 401, message = "Unauthorized"), @ApiResponse(code = 403, message = "Forbidden"), @ApiResponse(code = 404, message = "Not Found"), @ApiResponse(code = 500, message = "Failure") }) public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) { return new Greeting(counter.incrementAndGet(), String.format(template, name)); } }

The model class also uses Swagger annotations to document its fields.

package hello; import com.fasterxml.jackson.annotation.JsonProperty; import io.swagger.annotations.ApiModelProperty; public class Greeting { private final long id; private final String content; public Greeting(long id, String content) { this.id = id; this.content = content; } public long getId() { return id; } @JsonProperty(required = true) @ApiModelProperty(notes = "The name of the user", required = true) public String getContent() { return content; } }

When the application runs, the Swagger UI displays the documented endpoints, parameters, and response models, providing an interactive API explorer.