configure a spring boot application to integrate swagger2

intergate Spring boot and Swagger2

1. make a file named SwaggerConfig

2. use annotation @Configuration and @EnableSwagger2 above the SwaggerConfig file

3. create Docket bean

   Swagger2 is enabled through the @EnableSwagger2annotation.

   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.

   Predicates for selection of RequestHandlers can be configured with the help of RequestHandlerSelectors and PahSelectors. Using any() for both will make documentation for your entire APIavailable through Swagger

   Example:

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
      @Bean
      public Docket api(){
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  //自行修改包路径
                  .apis(RequestHandlerSelectors.basePackage("com.example.demo.web.res"))
                  .paths(PathSelectors.any())
                  .build();
      }
      public ApiInfo apiInfo(){
          return new ApiInfoBuilder()
               ///页面标题
               .title("api文档")
                  .description("restful风格接口")
                  //服务条款网址
                  //.termsOfServiceUrl("http://blog.csdn.net/forezp")
                  .version("1.0")
               //创建人
                  //.contact(new Contact("帅呆了", "url", "email"))
                  .build();
      }
   }

   notes:

   add dependencies:

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.9.2</version>
       </dependency>
       <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.9.2</version>
       </dependency>

   Swagger UI is a built-in solution which makes user interaction with the Swagger-generated API documentation much easier.

   finally, you can test it in your browser by visiting http://localhost:8080/projectName/swagger-ui.html

   ​

   References:

   http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

4. How to use?

   Common Annotation :

   @Api：修饰整个类，描述Controller的作用

   @ApiOperation：描述一个类的一个方法，或者说一个接口

   @ApiParam：单个参数描述

   @ApiModel：用对象来接收参数

   @ApiProperty：用对象接收参数时，描述对象的一个字段

   @ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

5. if you want to scan multiple packages, how to fix it?

   RequestHandlerSelectors.basePackage("com.xxx") in springfox only support scanning single package

   so , you can refer the following:

   package com.xxx.swagger;
   
   import org.springframework.beans.factory.annotation.Value;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.context.annotation.PropertySource;
   import org.springframework.context.annotation.PropertySources;
   
   import springfox.documentation.RequestHandler;
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   import com.google.common.base.Function;
   import com.google.common.base.Optional;
   import com.google.common.base.Predicate;
   
   /**
   * Swagger2 UI配置
   * 
   * <pre>
   * 通过访问http://your ip:8090/api/swagger-ui.html查看发布的REST接口;
   * </pre>
   * 
   * @author 许畅
   * @since JDK1.7
   * @version 2017年10月19日 许畅 新建
   */
   @Configuration
   @PropertySources({ @PropertySource(value = "classpath:swagger2.properties", ignoreResourceNotFound = true, encoding = "UTF-8") })
   @EnableSwagger2
   public class Swagger2UIConfig {
   
      /**
       * 获取API标题
       */
      @Value("${swagger2.title}")
      public String title = "Spring Boot中使用Swagger2构建Restful API";
   
      /**
       * Swagger2创建Docket的Bean
       * 
       * @return Docket
       */
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
              //have no more space after ,
              .apis(Swagger2UIConfig.basePackage("com.xxx1,com.xxx2")).paths(PathSelectors.any()).build();
      }
   
      /**
       * Predicate that matches RequestHandler with given base package name for the class of the handler method.
       * This predicate includes all request handlers matching the provided basePackage
       *
       * @param basePackage - base package of the classes
       * @return this
       */
      public static Predicate<RequestHandler> basePackage(final String basePackage) {
          return new Predicate<RequestHandler>() {
   
              @Override
              public boolean apply(RequestHandler input) {
                  return declaringClass(input).transform(handlerPackage(basePackage)).or(true);
              }
          };
      }
   
      /**
       * 处理包路径配置规则,支持多路径扫描匹配以逗号隔开
       * 
       * @param basePackage 扫描包路径
       * @return Function
       */
      private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
          return new Function<Class<?>, Boolean>() {
   
              @Override
              public Boolean apply(Class<?> input) {
                  for (String strPackage : basePackage.split(",")) {
                      boolean isMatch = input.getPackage().getName().startsWith(strPackage);
                      if (isMatch) {
                          return true;
                      }
                  }
                  return false;
              }
          };
      }
   
      /**
       * @param input RequestHandler
       * @return Optional
       */
      private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
          return Optional.fromNullable(input.declaringClass());
      }
   
      /**
       * Swagger2创建该Api的基本信息
       * 
       * @return ApiInfo
       */
      @Bean
      public ApiInfo apiInfo() {
          return new ApiInfoBuilder().title(title)
              .description("更多Swagger2配置相关文章请关注：https://springfox.github.io/springfox/docs/current/")
              .termsOfServiceUrl("https://springfox.github.io/springfox/docs/current/").version("1.0").build();
      }
   
   }
   reference:
   https://blog.csdn.net/melody_susan/article/details/80339542
   

Q: how to render a map like using @apiModel to render a entity?