【knife4j】接口分组配置；登录拦截器放行；登录拦截器配置token；给全局异常处理类添加注解；解决上传文件不显示文件域；参数扁平化；@Parameter-洪萨配资

@Parameter

@Parameter是用来为 API 接口参数添加元数据（描述信息）的注解，这些信息最终会生成到 OpenAPI 规范的文档中，供 Knife4j/Swagger UI 等工具展示

简单来说：它让 API 的使用者能清楚地知道每个参数的含义、是否必填、格式要求等

@Operation(summary = "查询指定课程的学习记录") @GetMapping("/course/{courseId}") public LearningLessonDTO queryLearningRecordByCourse( @PathVariable @Parameter(description = "课程id", example = "2") Long courseId){ return recordService.queryLearningRecordByCourse(courseId); }

参数扁平化

springdoc: default-flat-param-object: true

效果：

没有添加配置效果：

接口分组配置

088-尚庭公寓-项目开发-后台管理-初始配置-Knife4j_哔哩哔哩_bilibili

后台管理系统和移动端接口不同

web

@Configuration public class Knife4jConfiguration { // 配置了接口文档的基本信息 @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("后台管理系统API") .version("1.0") .description("后台管理系统API"); } // 下面的Bean对应一个个的接口分组 // @Bean public GroupedOpenApi systemAPI() { return GroupedOpenApi.builder().group("系统信息管理"). pathsToMatch( "/admin/system/**" ). build(); } @Bean public GroupedOpenApi loginAPI() { return GroupedOpenApi.builder().group("登录管理"). pathsToMatch( "/admin/login/**", "/admin/info"). build(); } @Bean public GroupedOpenApi apartmentAPI() { return GroupedOpenApi.builder().group("公寓信息管理"). pathsToMatch( "/admin/apartment/**", "/admin/room/**", "/admin/label/**", "/admin/facility/**", "/admin/fee/**", "/admin/attr/**", "/admin/payment/**", "/admin/region/**", "/admin/term/**", "/admin/file/**" ).build(); } @Bean public GroupedOpenApi leaseAPI() { return GroupedOpenApi.builder().group("租赁信息管理"). pathsToMatch( "/admin/appointment/**", "/admin/agreement/**" ).build(); } @Bean public GroupedOpenApi userAPI() { return GroupedOpenApi.builder().group("平台用户管理"). pathsToMatch( "/admin/user/**" ).build(); } }

app

@Configuration public class Knife4jConfiguration { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("APP接口") .version("1.0") .description("用户端APP接口");+ } @Bean public GroupedOpenApi userAPI() { return GroupedOpenApi.builder().group("用户信息"). pathsToMatch("/app/user/**"). build(); } @Bean public GroupedOpenApi loginAPI() { return GroupedOpenApi.builder().group("登录信息"). pathsToMatch("/app/login/**", "/app/info"). build(); } @Bean public GroupedOpenApi personAPI() { return GroupedOpenApi.builder().group("个人信息"). pathsToMatch( "/app/history/**", "/app/appointment/**", "/app/agreement/**" ). build(); } @Bean public GroupedOpenApi lookForRoomAPI() { return GroupedOpenApi.builder().group("找房信息"). pathsToMatch( "/app/apartment/**", "/app/room/**", "/app/payment/**", "/app/region/**", "/app/term/**" ). build(); } }

登录拦截器放行

3.5 访问权限控制 | Knife4j

这些是knife4j需要的路径

给登录拦截器放行

@Configuration @RequiredArgsConstructor public class WebConfig implements WebMvcConfigurer { private final LoginInterceptor loginInterceptor; @Override public void addInterceptors(InterceptorRegistry registry) { // 将拦截器注册到Spring MVC的拦截器链中 registry.addInterceptor(loginInterceptor) .addPathPatterns("/**") .excludePathPatterns( "/v3/api-docs/**", "/doc.html", "/swagger-ui/**", "/swagger-resources/**" ); } }

让接口文档带上token

146-尚庭公寓-项目开发-后台管理-系统管理-登录管理-拦截器_哔哩哔哩_bilibili

让接口文档在发送测试请求时，带上token

之后就能通过拦截器的验证

这个全局参数只对当前分组生效，有多个分组要设置多次

参数名称和前端约定好

参数值获取真实的token

如果是自己生成token，为了方便可以调整有效期

生成完后，再恢复成一小时的有效期

需要给全局异常处理类添加注解

关于异常java.lang.NoSuchMethodError: ‘void org.springframework.web.method.ControllerAdviceBean.＜init＞(ja_java.lang.nosuchmethoderror: 'void org.springframe-CSDN博客

使用@Hidden，不然接口文档报错

// common模块/exception /** * 全局异常处理器 * Knife4j（Swagger）全局异常添加@Hidden防止报错 */ @Hidden @ControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(Exception.class) @ResponseBody public Result handle(Exception e){ e.printStackTrace(); return Result.fail(); } }

解决上传文件不显示文件域

【Knife4j】解决SpringBoot整合Knife4j 3.0.3 文件上传不显示文件域_knife4j调试文件传参,选不了文件-CSDN博客

使用@RequestPart，我之前使用了@RequestParam，没用

@Tag(name = "文件管理") @RequestMapping("/file") @RestController @RequiredArgsConstructor public class FileUploadController { private final FileService fileService; @Operation(summary = "上传文件") @PostMapping("upload") public Result<String> upload(@RequestPart("file") MultipartFile file) throws ServerException, InsufficientDataException, ErrorResponseException, IOException, NoSuchAlgorithmException, InvalidKeyException, InvalidResponseException, XmlParserException, InternalException { String url = fileService.uploadFile(file); return Result.ok(url); } }