springboot+swagger2

springboot+swagger2

小序

新公司的第二个项目，是一个配置管理终端机(比如:自动售卖机，银行取款机)的web项目，之前写过一个分模块的springboot框架，就在那个框架基础上进行了改造。改造后的框架可以说能满足普通项目的所有需求，大家可以循环利用哈。后续我会附上摘出来的框架源码，和大家一起学习进步。今天主要是说一下springboot配置在线接口文档swagger2。

添加jar

在你的maven管理的项目的pom.xml中添加

 <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger2</artifactId>
             <version>2.2.2</version>
         </dependency>
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger-ui</artifactId>
             <version>2.2.2</version>
         </dependency>

添加swagger2的配置类

 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

 import springfox.documentation.builders.ApiInfoBuilder;
 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;

 /**
  * Swagger2配置类 在与spring boot集成时，放在与Application.java同级的目录下。
  * 通过@Configuration注解，让Spring来加载该类配置。 再通过@EnableSwagger2注解来启用Swagger2。
  */
 @Configuration
 @EnableSwagger2
 public class Swagger2 {

     /**
      * 创建API应用 apiInfo() 增加API相关信息
      * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
      * 本例采用指定扫描的包路径来定义指定要建立API的目录。
      *
      * @return
      */
     @Bean
     public Docket createRestApi() {
         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                 .apis(RequestHandlerSelectors.basePackage("com.11.22.33.controller"))//此处改为你的接口所在的包路径
                 .paths(PathSelectors.any()).build();
     }

     /**
      * 创建该API的基本信息（这些基本信息会展现在文档页面中） 访问地址：http://项目实际地址/swagger-ui.html
      *
      * @return
      */
     private ApiInfo apiInfo() {
         return new ApiInfoBuilder().title("title").description("description").contact("作者")
                 .version("1.0").build();//此处改为你自己的项目名称，描述，作者，版本
     }
 }

controller添加swagger2注解

• 例一

多个参数的话，添加多个@ApiImplicitParam即可，逗号分隔。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(value = "DeviceProductController|终端设备下的产品的相关接口")
@RequestMapping(RequestUrl.DEVEICE_PRODUCT_LIST)
@RestController
public class DeviceProductController {
    @Autowired
    private DeviceProductService deviceProductService;

    @ApiOperation(value="根据设备编号获取产品列表")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="query", name = "deviceId", value = "设备编号", required = true, dataType = "String")
    })
    @RequestMapping(method = RequestMethod.GET)
    String deveiceInfos(String  deviceId, HttpServletRequest request) {
        String result = deviceProductService.getDeviceProductList(deviceId);
        return result;
    }
}

• 例二

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(value = "DeviceInfoController|终端设备的相关接口")
@RequestMapping(RequestUrl.DEVEICE_INFO_LIST)
@RestController
public class DeviceInfoController {
    @Autowired
    private DeviceInfoService deveiceInfoService;

    @ApiOperation(value="分页获取终端列表datatable的数据格式")
    @RequestMapping(method = RequestMethod.GET)
    String deveiceInfos(@ModelAttribute Gpage page, HttpServletRequest request) {
        String result = deveiceInfoService.deveiceInfos(page, request);
        return result;
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel(value="分页对象类型")
@Data
public class Gpage{

    @ApiModelProperty(value="每页显示个数" ,required=true)
    private int length = 10;
    @ApiModelProperty(value="开始坐标" ,required=true)
    private int start;
}

在线接口文档访问路径

我本地启用的是8081端口，所以访问路径是http://localhost:8081/swagger-ui.html

遇到的坑

• 如果你配置了spring.resources.static-locations,那你就需要把swagger-ui.html也要加进去

解决办法：新建类MyWebAppConfigurer,添加如下代码即可

 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

 @Configuration
 public class MyWebAppConfigurer extends WebMvcConfigurerAdapter {
     /**
      * 添加swagger-ui.html
      */
     @Override
     public void addResourceHandlers(ResourceHandlerRegistry registry) {
          registry.addResourceHandler("swagger-ui.html")
          .addResourceLocations("classpath:/META-INF/resources/");
          registry.addResourceHandler("/webjars*")
          .addResourceLocations("classpath:/META-INF/resources/webjars/");
         super.addResourceHandlers(registry);
     }
 }

• 如果你配置了拦截器或者过滤器，也要过滤掉swagger的相关路径