How to configure Swagger for your Spring Boot project

Inspired by https://springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot

  1. Configure your maven to support Swagger.
    1. <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.7.0</version>
      </dependency>
      <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.7.0</version>
      </dependency>
      <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-data-rest</artifactId>
      <version>2.7.0</version>
      </dependency>
      <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-bean-validators</artifactId>
      <version>2.7.0</version>
      </dependency>
      
  2. Create a SwaggerConfig file.
    package com.xxx.rest;
    
    import com.fasterxml.classmate.TypeResolver;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.ApplicationContext;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Import;
    import org.springframework.context.annotation.ComponentScan;
    import org.springframework.http.ResponseEntity;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.context.request.async.DeferredResult;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.builders.ResponseMessageBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.schema.WildcardType;
    import springfox.documentation.service.ApiKey;
    import springfox.documentation.service.AuthorizationScope;
    import springfox.documentation.service.SecurityReference;
    import springfox.documentation.service.Tag;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spi.service.contexts.SecurityContext;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger.web.ApiKeyVehicle;
    import springfox.documentation.swagger.web.SecurityConfiguration;
    import springfox.documentation.swagger.web.UiConfiguration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    //import springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration;
    
    import java.util.List;
    
    import static com.google.common.collect.Lists.*;
    import static springfox.documentation.schema.AlternateTypeRules.*;
    
    @SpringBootApplication
    @EnableSwagger2
    @ComponentScan("com.xxx.rest")
    //@Import({springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration.class, springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration.class})
    public class SwaggerConfig {
    
    public static void main(String[] args) {
    ApplicationContext ctx = SpringApplication.run(SwaggerConfig.class, args);
    }
    
     
    
    @Bean
    public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
    .select()
    .apis(RequestHandlerSelectors.any())
    .paths(PathSelectors.any())
    .build()
    .pathMapping("/")
    .genericModelSubstitutes(ResponseEntity.class)
    .alternateTypeRules(
    newRule(typeResolver.resolve(DeferredResult.class,
    typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
    typeResolver.resolve(WildcardType.class)))
    .useDefaultResponseMessages(false)
    .globalResponseMessage(RequestMethod.GET,
    newArrayList(new ResponseMessageBuilder()
    .code(500)
    .message("500 message")
    .responseModel(new ModelRef("Error"))
    .build()))
    .securitySchemes(newArrayList(apiKey()))
    .securityContexts(newArrayList(securityContext()))
    .enableUrlTemplating(true)
    .globalOperationParameters(
    newArrayList(new ParameterBuilder()
    .name("someGlobalParameter")
    .description("Description of someGlobalParameter")
    .modelRef(new ModelRef("string"))
    .parameterType("query")
    .required(true)
    .build()))
    .tags(new Tag("Pet Service", "All apis relating to pets"))
    ;
    }
    
    @Autowired
    private TypeResolver typeResolver;
    
    private ApiKey apiKey() {
    return new ApiKey("mykey", "api_key", "header");
    }
    
    private SecurityContext securityContext() {
    return SecurityContext.builder()
    .securityReferences(defaultAuth())
    .forPaths(PathSelectors.regex("/*"))
    .build();
    }
    
    List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope
    = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return newArrayList(
    new SecurityReference("mykey", authorizationScopes));
    }
    
    @Bean
    SecurityConfiguration security() {
    return new SecurityConfiguration(
    "test-app-client-id",
    "test-app-client-secret",
    "test-app-realm",
    "test-app",
    "apiKey",
    ApiKeyVehicle.HEADER,
    "api_key",
    "," /*scope separator*/);
    }
    
    @Bean
    UiConfiguration uiConfig() {
    return new UiConfiguration(
    "validatorUrl",// url
    "none", // docExpansion => none | list
    "alpha", // apiSorter => alpha
    "schema", // defaultModelRendering => schema
    UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS,
    false, // enableJsonEditor => true | false
    true, // showRequestHeaders => true | false
    60000L); // requestTimeout => in milliseconds, defaults to null (uses jquery xh timeout)
    }
    }
    
  3. deploy your spring boot application then you should be able to visit your restful API docs
    1. swagger