Swagger with Spring Boot

By

Swagger For Documenting Rest Endpoints


Swagger 2 is an open-source project used to describe and document RESTful APIs
We will setup the swagger endpoints for the employee and oauth-client microservices.
For more details regarding swagger, please refer to the official website:
https://swagger.io/tools/swagger-ui/

The employee microservice and the oauth client setup have been explained in my previous posts. Kindly refer them to setup these applications.

  • Adding maven dependencies

          <dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
  </dependency>

  <dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
  </dependency>
  • Setting up Swagger configuration
    @Configuration
@EnableSwagger2
public class SwaggerConfiguration {

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .globalOperationParameters(Collections.singletonList(new ParameterBuilder()
        .name("Authorization").description("Authorization header")
        .modelRef(new ModelRef("string")).parameterType("header").required(true).build()))
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.prashant.employee.rest"))
      .paths(PathSelectors.any())

      .build()
      .apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfo(
      "Employee Microservice",
      "Employee microservice which exposes operation to deal with employee data",
      "0.0.1-SNAPSHOT",
      "Terms of service",
      new Contact("Prashant Hariahran", "https://prashanthariharan.wixsite.com/prashant/blog", ""),
      "License of API", "API license URL", Collections.emptyList());
  }

  @Bean
  UiConfiguration uiConfig() {
    return UiConfigurationBuilder.builder()
      .deepLinking(true)
      .displayOperationId(false)
      .defaultModelsExpandDepth(1)
      .defaultModelExpandDepth(1)
      .defaultModelRendering(ModelRendering.EXAMPLE)
      .displayRequestDuration(false)
      .docExpansion(DocExpansion.NONE)
      .filter(false)
      .maxDisplayedTags(null)
      .operationsSorter(OperationsSorter.ALPHA)
      .showExtensions(false)
      .tagsSorter(TagsSorter.ALPHA)
      .supportedSubmitMethods(UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS)
      .validatorUrl(null)
      .build();
  }

}

Note: the following code in the docket definition is only required for oauth secured resources( like employee microservice) and not required fro oauth client.

.globalOperationParameters(Collections.singletonList(new ParameterBuilder()
.name("Authorization").description("Authorization header")
.modelRef(new ModelRef("string")).parameterType("header").required(true).build()))

This basically enforces the user to enter the oauth token as a bear token on every request.
Eg Bearer 

Adding documentation to Rest controller

@RestController
@RequestMapping("/employee")
@Api(value = "Employee Microservice", description = "Operations pertaining to Employee Microservice")
public class EmployeeRestService {

Ignoring swagger endpoints from spring security:

Add the following entries in the application.properties file:

ignore.security.endpoints=/actuator/**;/api/**;/v2/**;/swagger-ui.html;/swagger-resources/**;/webjars/**;

Note: We have previously configured in our microservices the following class to read the endpoints from the application.properties that need to be ignored by spring-security.

@Configuration
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {

@Value("${ignore.security.endpoints}")
String ignoredEndpoints;

@Override
public void configure(WebSecurity web) {
web.ignoring().mvcMatchers(ignoredEndpoints.split(";"));

}

Verfiying Swagger endpoints:

Oncer the above configurations are done, we can check the following endpoints :

http://localhost:7003/v2/api-docs
http://localhost:7003/swagger-ui.html

As stated above, the swagger ui in our case is just for documentation purposes and cannot be used to invoke the operations as we will need some additional configurations for the same.

Swagger also provides a lot of custom configurations which can be evaluated based on the application requirements.

Similar setup is also done for the oauth-client.
The code can be found on GitHub.