如何配置Swagger识别类级路径变量schoolId并生成有效请求URL？

这个问题我之前也碰到过，正好有几个实用的解决办法，你可以根据自己的情况选：

方案1：添加隐藏的路径变量参数 #

在方法参数里声明schoolId，但用@ApiParam(hidden = true)标记为隐藏。这样Swagger会自动识别这个路径变量并生成可输入的占位符，同时不会在接口文档的参数列表里显示它，方法里也不用实际使用这个参数（毕竟过滤器会处理）：

@RestController
@RequiredArgsConstructor
@RequestMapping("/schools/{schoolId}/teachers")
public class TeacherController {
    private final TeacherRepository teacherRepository;

    @GetMapping("/{teacherId}")
    public Teacher get(
        // 添加这个参数但标记为隐藏，不影响业务逻辑
        @PathVariable("schoolId") @ApiParam(hidden = true) Long schoolId,
        @PathVariable Long teacherId
    ) {
        return teacherRepository.findById(teacherId);
    }
}

这个方案简单直接，代码改动极小，适合单个接口的场景。

方案2：用@ApiImplicitParams声明路径变量 #

如果不想修改方法签名，可以在方法上添加@ApiImplicitParams注解，手动声明类级的路径变量。这样Swagger会识别这个变量并生成对应的输入框，完全不需要改动方法参数：

@RestController
@RequiredArgsConstructor
@RequestMapping("/schools/{schoolId}/teachers")
public class TeacherController {
    private final TeacherRepository teacherRepository;

    @GetMapping("/{teacherId}")
    @ApiImplicitParams({
        @ApiImplicitParam(
            name = "schoolId",
            value = "学校ID（过滤器自动处理）",
            required = true,
            dataTypeClass = Long.class,
            paramType = "path"
        )
    })
    public Teacher get(@PathVariable Long teacherId) {
        return teacherRepository.findById(teacherId);
    }
}

这个方案适合不想污染方法参数的场景，缺点是每个需要的接口都要单独添加注解。

方案3：全局统一处理（多接口场景首选） #

如果你的项目里有很多Controller都用了类级的路径变量，可以写一个全局的Swagger自定义处理器，自动扫描类级@RequestMapping里的路径变量并添加到Swagger文档中：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.AnnotationUtils;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.service.OperationCustomizer;

import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

@Configuration
public class SwaggerConfig {

    @Bean
    public OperationCustomizer classLevelPathVariableCustomizer() {
        return (operation, handlerMethod) -> {
            // 获取Controller类上的@RequestMapping注解
            RequestMapping classRequestMapping = AnnotationUtils.findAnnotation(
                    handlerMethod.getBeanType(), RequestMapping.class);
            
            if (classRequestMapping != null) {
                Pattern pathVarPattern = Pattern.compile("\\{(.*?)\\}");
                List<RequestParameter> parameters = new ArrayList<>();
                
                for (String path : classRequestMapping.value()) {
                    Matcher matcher = pathVarPattern.matcher(path);
                    while (matcher.find()) {
                        String varName = matcher.group(1);
                        // 检查是否已经存在该参数，避免重复添加
                        boolean exists = operation.getRequestParameters().stream()
                                .anyMatch(p -> p.getName().equals(varName));
                        if (!exists) {
                            RequestParameter param = new RequestParameterBuilder()
                                    .name(varName)
                                    .description("类级路径变量（过滤器自动处理）")
                                    .required(true)
                                    .in("path")
                                    .query(paramBuilder -> paramBuilder.scalarModel(ScalarType.LONG)) // 根据实际类型调整
                                    .build();
                            parameters.add(param);
                        }
                    }
                }
                
                operation.getRequestParameters().addAll(0, parameters);
            }
            return operation;
        };
    }
}

这个方案一劳永逸，所有类级的路径变量都会被Swagger自动识别，不需要每个接口都单独配置。

内容的提问来源于stack exchange，提问作者Shirabu