@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);
    }
}