springboot+swagger2

小序

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

添加jar

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

 1 <dependency>
 2             <groupId>io.springfox</groupId>
 3             <artifactId>springfox-swagger2</artifactId>
 4             <version>2.2.2</version>
 5         </dependency>
 6         <dependency>
 7             <groupId>io.springfox</groupId>
 8             <artifactId>springfox-swagger-ui</artifactId>
 9             <version>2.2.2</version>
10         </dependency>

添加swagger2的配置类

 1 import org.springframework.context.annotation.Bean;
 2 import org.springframework.context.annotation.Configuration;
 3
 4 import springfox.documentation.builders.ApiInfoBuilder;
 5 import springfox.documentation.builders.PathSelectors;
 6 import springfox.documentation.builders.RequestHandlerSelectors;
 7 import springfox.documentation.service.ApiInfo;
 8 import springfox.documentation.spi.DocumentationType;
 9 import springfox.documentation.spring.web.plugins.Docket;
10 import springfox.documentation.swagger2.annotations.EnableSwagger2;
11
12 /**
13  * Swagger2配置类 在与spring boot集成时，放在与Application.java同级的目录下。
14  * 通过@Configuration注解，让Spring来加载该类配置。 再通过@EnableSwagger2注解来启用Swagger2。
15  */
16 @Configuration
17 @EnableSwagger2
18 public class Swagger2 {
19
20     /**
21      * 创建API应用 apiInfo() 增加API相关信息
22      * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
23      * 本例采用指定扫描的包路径来定义指定要建立API的目录。
24      *
25      * @return
26      */
27     @Bean
28     public Docket createRestApi() {
29         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
30                 .apis(RequestHandlerSelectors.basePackage("com.11.22.33.controller"))//此处改为你的接口所在的包路径
31                 .paths(PathSelectors.any()).build();
32     }
33
34     /**
35      * 创建该API的基本信息（这些基本信息会展现在文档页面中） 访问地址：http://项目实际地址/swagger-ui.html
36      *
37      * @return
38      */
39     private ApiInfo apiInfo() {
40         return new ApiInfoBuilder().title("title").description("description").contact("作者")
41                 .version("1.0").build();//此处改为你自己的项目名称，描述，作者，版本
42     }
43 }

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,添加如下代码即可

 1 import org.springframework.context.annotation.Configuration;
 2 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 3 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
 4
 5 @Configuration
 6 public class MyWebAppConfigurer extends WebMvcConfigurerAdapter {
 7     /**
 8      * 添加swagger-ui.html
 9      */
10     @Override
11     public void addResourceHandlers(ResourceHandlerRegistry registry) {
12          registry.addResourceHandler("swagger-ui.html")
13          .addResourceLocations("classpath:/META-INF/resources/");
14          registry.addResourceHandler("/webjars*")
15          .addResourceLocations("classpath:/META-INF/resources/webjars/");
16         super.addResourceHandlers(registry);
17     }
18 }

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