Swagger2结合Pageable操作细节

Posted by 王进 on 11-20,2019

springboot2.0对Pageable接口的PageRequest实现类进行了封装. 私有化了构造方法. 增加了PageRequest.of(...)等静态方法. 因此Controller不能直接接收PageRequest对象.

首先我们看下默认swagger2的参数:

image.png

由于参数是page,size,sort. 而swagger2生成的事pageSize,pageNumber. 所以我们必须自定义实现:


    @Bean
    public AlternateTypeRuleConvention pageableConvention(final TypeResolver resolver) {
        return new AlternateTypeRuleConvention() {
            @Override
            public int getOrder() {
                return Ordered.LOWEST_PRECEDENCE;
            }
            @Override
            public List<AlternateTypeRule> rules() {
                AlternateTypeRule alternateTypeRule = newRule(resolver.resolve(Pageable.class), resolver.resolve(Page.class));
                return new ArrayList<AlternateTypeRule>(){{this.add(alternateTypeRule);}};
            }
        };
    }

    @ApiModel
    @Data
    static class Page {
        @ApiModelProperty("第多少页,从0开始计数")
        private Integer page;

        @ApiModelProperty("每页显示多少数据")
        private Integer size;

        @ApiModelProperty("按属性排序,格式:属性,ASC或者DESC  例如对id倒序排序:id,desc")
        private List<String> sort;
    }


此时再看swagger2

image.png

swagger2全部配置:

package com.wangjin.config;

import com.fasterxml.classmate.TypeResolver;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.Ordered;
import org.springframework.data.domain.Pageable;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.AlternateTypeRule;
import springfox.documentation.schema.AlternateTypeRuleConvention;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

import static springfox.documentation.schema.AlternateTypeRules.newRule;

/**
 * @author wajn
 * @date 2019/11/15  21:15
 */
@Profile({"dev", "test"})
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private List<Parameter> getGlobalOperationParameters() {
        List<Parameter> pars = new ArrayList<>(1);
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        // header query cookie
        parameterBuilder.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(true);
        pars.add(parameterBuilder.build());
        return pars;
    }



    @Bean
    public AlternateTypeRuleConvention pageableConvention(final TypeResolver resolver) {
        return new AlternateTypeRuleConvention() {
            @Override
            public int getOrder() {
                return Ordered.LOWEST_PRECEDENCE;
            }
            @Override
            public List<AlternateTypeRule> rules() {
                AlternateTypeRule alternateTypeRule = newRule(resolver.resolve(Pageable.class), resolver.resolve(Page.class));
                return new ArrayList<AlternateTypeRule>(){{this.add(alternateTypeRule);}};
            }
        };
    }

    @ApiModel
    @Data
    static class Page {
        @ApiModelProperty("第多少页,从0开始计数")
        private Integer page;

        @ApiModelProperty("每页显示多少数据")
        private Integer size;

        @ApiModelProperty("按属性排序,格式:属性,ASC或者DESC  例如对id倒序排序:id,desc")
        private List<String> sort;
    }


    @Bean
    public Docket createRestApi() {
        System.out.println("createRestApi Docket...");
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(getGlobalOperationParameters())
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wangjin.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .build();
    }

}