Swagger

swagger简介

• 帮助管理api

• 添加jar包 添加swagger2与swaggerui两个包

<!-- 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

• 添加配置类 开启swagger2

@Bean
public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
//                .enable(false)//关闭swagger
        .select()//选择扫描那些包下的api
        .apis(RequestHandlerSelectors.basePackage("com.liuyulin10.swagger.controller"))
//                .paths("/"liuyulin10/**)//过滤
        .build();//工厂模式
        }


private ApiInfo apiInfo(){
        return new ApiInfo("study swagger","description","1.0",
        "urn:tos",DEFAULT_CONTACT,"Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());
        }

• 测试默认配置 访问/swagger-ui.html 查看接口信息

• 高版本的spring使用swagger会报错 在swagger配置类中添加一个bean 解决问题

@Bean
public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor(){
        return new BeanPostProcessor(){

@Override
public Object postProcessAfterInitialization(Object bean,String beanName)throws BeansException{
        if(bean instanceof WebMvcRequestHandlerProvider||bean instanceof WebFluxRequestHandlerProvider){
        customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
        }
        return bean;
        }

private<T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings){
        List<T> copy=mappings.stream()
        .filter(mapping->mapping.getPatternParser()==null)
        .collect(Collectors.toList());
        mappings.clear();
        mappings.addAll(copy);
        }

@SuppressWarnings("unchecked")
private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean){
        try{
        Field field=ReflectionUtils.findField(bean.getClass(),"handlerMappings");
        field.setAccessible(true);
        return(List<RequestMappingInfoHandlerMapping>)field.get(bean);
        }catch(IllegalArgumentException|IllegalAccessException e){
        throw new IllegalStateException(e);
        }
        }
        };
        }

• 真的无语 添加完bean之后能打开swagger-api.html了 但是看不到接口 在配置文件中添加配置之后恢复

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

• 可以通过配置控制swagger开启的环境 以及显示的组名 配置多个Docket就可以有多个组

@Bean
public Docket docket(Environment environment){

        //设置要显示的swagger的环境
        Profiles profiles=Profiles.of("dev");
        //获取项目环境 通过监听判断是否处在自己设定的环境中
        boolean flag=environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(flag)//关闭swagger
        .groupName("liuyulin10")
        .select()//选择扫描那些包下的api
        .apis(RequestHandlerSelectors.basePackage("com.liuyulin10.swagger.controller"))
//                .paths("/"liuyulin10/**)//过滤
        .build();//工厂模式
        }

swagger注解

@Api()

用在请求类上，表示对类的说明，也代表了这个类是swagger资源

参数：

• tags：说明该类的作用，参数是个数组，可以填多个

• value： 没用，不用配置

• description：描述

@ApiOperation()

用于方法上，表示一个http请求访问该方法的操作

参数：

• value：方法的作用和用途

• notes：方法的注意事项和备注

• tags：说明该方法的作用，数组，可以填多个

@ApiModel()

用于响应实体类上，用于说明实体的作用

参数：

• description：描述实体类的作用

@ApiModelProperty()

用在属性上，描述实体类的属性

参数：

• value：描述参数的意义

• name：参数的变量名

• required：是否必填

@ApiImplicitParams()

用在请求方法上，包含多@ApiImplicitParam

@ApiImplicitParam()

用于方法上，表示单独的请求参数

参数：

• name：参数名

• value：参数说明

• dataType：数据类型

• paramType：表示参数放在哪

  • header：用@RequestHeader获取的参数

  • query：用@RequestParam获取的参数

  • path：用@PathVariable获取的参数

  • body：请求体

  • form：表单

@ApiParam()

用于方法，参数，字段说明，表示对参数的要求和说明

参数：

• name：参数名称

• value：参数的简要说明

• defaultValue：参数默认值

• required：是否必填

@ApiResponses()

用于请求的方法上，根据响应码表示不同的响应，一个@ApiResponses包含多个@ApiResponse

@ApiResponse()

用在请求的方法上，表示不同的响应

参数：

• code：响应码

• message：响应消息

@ApiIgnore()

用于类或者方法上，不被显示在页面上

@Profile()

用于配置类上，表示支队开发和测试环境有用