Part 3: Setting Up Swagger2 with a Spring REST API

3 min readApr 28, 2020

Part 1: Write Restful api with spring boot
Part 2: Connect Restful api with MySQL

It is important to have proper specifications for the back-end APIs, that should be informative, readable, and easy to follow. Moreover, reference documentation should simultaneously describe every change in the API. Maintaining this manually is a hard job, so automation of the process would be great.

We will achieve this by using Swagger and Springfox. If you are not familiar with Swagger, you can visit its web page to learn more before continuing with this article. And similarly Swagger UI (Springfox) is a built-in solution which makes user interaction with the Swagger-generated API documentation much easier.

Let’s get to the point. Add following 2 dependencies in your gradle build.

dependencies {
    implementation("io.springfox:springfox-swagger-ui:2.8.0")
    implementation("io.springfox:springfox-swagger2:2.8.0")
    ......
}

Springfox works by examining an application, once, at runtime to infer API semantics based on spring configurations, class structure and various compile time java Annotations. Now in our Application class we will add following code.

@SpringBootApplication
@EnableSwagger2
class TodoApplication{

   @Bean
   fun docket(apiInfo: ApiInfo): Docket {
      return Docket(DocumentationType.SWAGGER_2)
            .groupName("todo")
            .useDefaultResponseMessages(false)
            .apiInfo(apiInfo)
            .select()
            .build()
   }

   @Bean
   fun apiInfo(): ApiInfo {
      return ApiInfoBuilder()
            .title("Todo app")
            .description("API to save and retreive tasks")
            .version("1.0.0")
            .build()
   }   @Bean
   fun restTemplate(builder: RestTemplateBuilder): RestTemplate {
      return builder.build();
   }   @Bean
   fun uiConfiguration(): UiConfiguration {
      return UiConfigurationBuilder.builder()
            .deepLinking(true)
            .validatorUrl(null)
            .build()
   }
}

fun main(args: Array<String>) {
   runApplication<TodoApplication>(*args)
}

Key points:

Swagger 2 is enabled through the @EnableSwagger2 annotation.
The configuration of Swagger mainly centers around the Docket bean. After the Docket bean is defined, its select() method returns an instance of ApiSelectorBuilder, which provides a way to control the endpoints exposed by Swagger.
It is not always desirable to expose the documentation for your entire API. You can restrict Swagger’s response by passing parameters to the apis() and paths() methods of the Docket class.
Swagger also provides some default values in its response which you can customize. To change these values, you can use the apiInfo(ApiInfo apiInfo) method. The ApiInfo class that contains custom information about the API.
For more information about the security and other configuration, I found this article really helpful.