Spring Boot集成SpringFox 3.0与Pageable参数处理

Springfox 3.0有多个模块,提供了spring boot starter,与Spring Boot集成时仅需引入springfox-boot-starter,如下:

java 复制代码
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

如果您以前使用了Springfox 2.x,需要修改一下Swagger配置:

删除@EnableSwagger2注解,改为@EnableOpenApi

将Docket中的参数DocumentationType.SWAGGER_2改为DocumentationType.OAS_30

Springfox 3.0删除了一些第三方模块,如有引用需要替换

修改后的配置如下:

java 复制代码
package com.ys.config;
import com.fasterxml.classmate.TypeResolver;
import org.itrunner.heroes.exception.ErrorMessage;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.time.LocalDate;
import java.util.List;

import static java.util.List.of;

@EnableOpenApi
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .pathMapping("/")
                .directModelSubstitute(LocalDate.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .additionalModels(new TypeResolver().resolve(ErrorMessage.class))
                .useDefaultResponseMessages(false)
                .securitySchemes(of(authenticationScheme()))
                .securityContexts(of(securityContext()))
                .enableUrlTemplating(false);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Api Documentation")
                .description("Api Documentation")
                .contact(new Contact("xx", "http://xxxxxx", "xxxxx@163.com"))
                .version("1.0.0")
                .build();
    }

    private HttpAuthenticationScheme authenticationScheme() {
        return HttpAuthenticationScheme.JWT_BEARER_BUILDER.name("BearerToken").build();
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .operationSelector(operationContext ->
                        operationContext.requestMappingPattern().startsWith("/api/")
                )
                .build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return of(new SecurityReference("BearerToken", authorizationScopes));
    }
}

上面我们使用了HttpAuthenticationScheme构建Bearer Token Authentication,在Swagger UI界面点击Authorize时直接输出token值即可。

Springfox 3.0的Swagger UI地址,从http://host/context-path/swagger-ui.html 改成了 http://host/context-path/swagger-ui/ ,OAS 3.0的api docs地址默认为/v3/api-docs,因此Security中的ignore path要进行相应修改。

Pageable参数

当REST API的方法含有org.springframework.data.domain.Pageable参数时,Springfox根据接口生成pageNumber、pageSize、offset、paged、unpaged、sort.sorted、sort.unsorted等参数,这与Spring Boot实际使用的参数是不一致的,因此需要针对Pageable参数进行特殊处理。

我们使用OperationBuilderPlugin处理Pageable参数,如下:

java 复制代码
package com.ys.config;
import com.fasterxml.classmate.ResolvedType;
import com.fasterxml.classmate.TypeResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.annotation.Order;
import org.springframework.data.domain.Pageable;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.service.ResolvedMethodParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;

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

@Component
@Order
public class PageableParameterReader implements OperationBuilderPlugin {
    private final TypeResolver resolver;

    @Autowired
    public PageableParameterReader(TypeResolver resolver) {
        this.resolver = resolver;
    }

    @Override
    public void apply(OperationContext context) {
        List<ResolvedMethodParameter> methodParameters = context.getParameters();
        ResolvedType pageableType = resolver.resolve(Pageable.class);
        List<RequestParameter> parameters = new ArrayList<>();

        for (ResolvedMethodParameter methodParameter : methodParameters) {
            ResolvedType resolvedType = methodParameter.getParameterType();

            if (pageableType.equals(resolvedType)) {

                parameters.add(new RequestParameterBuilder()
                        .in(ParameterType.QUERY)
                        .name("page")
                        .query(q -> q.model(m -> m.scalarModel(ScalarType.INTEGER)))
                        .description("Results page you want to retrieve (0..N)").build());
                parameters.add(new RequestParameterBuilder()
                        .in(ParameterType.QUERY)
                        .name("size")
                        .query(q -> q.model(m -> m.scalarModel(ScalarType.INTEGER)))
                        .description("Number of records per page").build());
                parameters.add(new RequestParameterBuilder()
                        .in(ParameterType.QUERY)
                        .name("sort")
                        .query(q -> q.model(m -> m.collectionModel(c -> c.model(cm -> cm.scalarModel(ScalarType.STRING)))))
                        .description("Sorting criteria in the format: property(,asc|desc). "
                                + "Default sort order is ascending. "
                                + "Multiple sort criteria are supported.")
                        .build());
                context.operationBuilder().requestParameters(parameters);
            }
        }
    }

    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }

}

方案一:在Controller分页方法的Pageable参数前添加@ApiIgnore,忽略默认的参数解析:

复制代码
public ResponseEntity<List<DeviceDTO>> getAllDevices(@ApiIgnore @PageableDefault(sort = {"id"}, direction = Sort.Direction.DESC) Pageable pageable,
                                                     @RequestParam(required = false) @ApiParam(value = "关键字(序列号,地址,归属单位)") String keyword,

方案二:全局配置,在SwaggerConfig类的createRestApi方法中添加:.ignoredParameterTypes(Pageable.class)

java 复制代码
@EnableOpenApi
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ys.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .ignoredParameterTypes(Pageable.class)
                .pathMapping("/")
                .directModelSubstitute(LocalDate.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .additionalModels(new TypeResolver().resolve(ErrorMessage.class))
                .useDefaultResponseMessages(false)
                .securitySchemes(of(authenticationScheme()))
                .securityContexts(of(securityContext()))
                .enableUrlTemplating(false);
    }

修改后Swagger UI中显示的Pageable参数如下:

相关推荐
武昌库里写JAVA7 分钟前
【MySQL】MySQL数据库如何改名
java·vue.js·spring boot·sql·学习
钟离墨笺23 分钟前
Go 语言-->指针
开发语言·后端·golang
前端梭哈攻城狮43 分钟前
dify二开示例
前端·后端·python
该用户已不存在1 小时前
Node.js 真的取代了PHP吗?
前端·后端·node.js
二闹1 小时前
OpenCV识物:用代码“认出”物体
后端·opencv
花落人散处1 小时前
SpringAI——接入高德MCP服务
java·后端
超浪的晨1 小时前
Java 代理机制详解:从静态代理到动态代理,彻底掌握代理模式的原理与实战
java·开发语言·后端·学习·代理模式·个人开发
天天摸鱼的java工程师1 小时前
🧠 MySQL 索引结构有哪些?优缺点是什么?【原理 + 场景实战】
java·后端·面试
阿宙ppppp1 小时前
基于yolov5+LPRNet+flask+vue的车牌识别(1)
后端·图像识别
Java水解2 小时前
Spring AI模块化RAG架构解析:三阶段设计与实现详解
后端·spring