如何在Springfox中使用Swagger 2.0可复用参数？该特性是否受支持？

Great question! First off, yes, Springfox fully supports Swagger 2.0's reusable parameters feature — you've got a few solid ways to implement this depending on whether you need parameters across all your APIs or just specific endpoints. Let's break it down step by step:

1. 全局可复用参数（适用于全接口通用参数） #

If you have parameters that every API endpoint should include (like an Authorization header for authentication), you can register them globally in your Springfox Docket configuration. This saves you from repeating the same parameter definition on every controller method.

@Configuration
@EnableSwagger2 // 用@EnableOpenApi替代，如果是Springfox 3.x+版本
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.app.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(getGlobalParameters());
    }

    private List<Parameter> getGlobalParameters() {
        // 定义可复用的Authorization请求头参数
        Parameter authHeader = new ParameterBuilder()
                .name("Authorization")
                .description("JWT Token格式：Bearer {token}")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();

        // 可以添加更多全局参数
        return Arrays.asList(authHeader);
    }
}

配置完成后，你所有接口的Swagger文档都会自动带上这个Authorization请求头，无需在每个方法上重复定义。

2. 局部可复用参数（适用于部分接口） #

对于只在特定接口中用到的参数（比如分页参数pageNum和pageSize），你可以把参数定义封装到工具类中，然后在需要的地方直接引用，减少重复代码。

第一步：创建参数复用工具类 #

public class SwaggerParamHelpers {
    // 可复用的分页参数：页码
    public static ApiImplicitParam pageNumParam() {
        return new ApiImplicitParamBuilder()
                .name("pageNum")
                .value("页码，默认值为1")
                .dataType("int")
                .paramType("query")
                .defaultValue("1")
                .required(false)
                .build();
    }

    // 可复用的分页参数：每页条数
    public static ApiImplicitParam pageSizeParam() {
        return new ApiImplicitParamBuilder()
                .name("pageSize")
                .value("每页数据条数，默认值为10")
                .dataType("int")
                .paramType("query")
                .defaultValue("10")
                .required(false)
                .build();
    }
}

第二步：在控制器中引用复用参数 #

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理接口")
public class UserController {

    @GetMapping("/list")
    @ApiOperation("获取分页用户列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名模糊搜索关键词", paramType = "query"),
            // 直接引用预定义的分页参数
            SwaggerParamHelpers.pageNumParam(),
            SwaggerParamHelpers.pageSizeParam()
    })
    public ResponseEntity<List<User>> getUsers(
            @RequestParam(required = false) String username,
            @RequestParam(defaultValue = "1") int pageNum,
            @RequestParam(defaultValue = "10") int pageSize
    ) {
        // 业务逻辑实现
        return ResponseEntity.ok(new ArrayList<>());
    }

    @GetMapping("/roles")
    @ApiOperation("获取分页用户角色列表")
    @ApiImplicitParams({
            // 再次复用相同的分页参数
            SwaggerParamHelpers.pageNumParam(),
            SwaggerParamHelpers.pageSizeParam()
    })
    public ResponseEntity<List<Role>> getUserRoles(
            @RequestParam(defaultValue = "1") int pageNum,
            @RequestParam(defaultValue = "10") int pageSize
    ) {
        // 业务逻辑实现
        return ResponseEntity.ok(new ArrayList<>());
    }
}

这样你只需要定义一次分页参数，就能在所有需要分页的接口中复用。

3. 进阶：使用Swagger 2.0的$ref语法 #

如果你想严格遵循Swagger 2.0规范（通过$ref引用components中的参数），Springfox也支持这种方式。你可以先在Swagger的components部分定义可复用参数，然后在接口中引用。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.app.controller"))
                .paths(PathSelectors.any())
                .build()
                .swaggerGenerator(new SwaggerGenerator() {
                    @Override
                    public Swagger generate() {
                        Swagger swagger = super.generate();
                        // 在components中定义可复用参数
                        Map<String, Parameter> reusableParams = new HashMap<>();
                        reusableParams.put("authorizationHeader", new Parameter()
                                .name("Authorization")
                                .in("header")
                                .description("JWT Token格式：Bearer {token}")
                                .required(false)
                                .type(new StringProperty()));
                        swagger.getComponents().parameters(reusableParams);
                        return swagger;
                    }
                });
    }
}

然后在控制器中通过ref属性引用该参数：

@GetMapping("/{userId}")
@ApiOperation("获取用户详情")
@ApiImplicitParams({
        @ApiImplicitParam(ref = "#/components/parameters/authorizationHeader"),
        @ApiImplicitParam(name = "userId", value = "目标用户ID", paramType = "path", required = true)
})
public ResponseEntity<User> getUserDetail(@PathVariable Long userId) {
    // 业务逻辑实现
    return ResponseEntity.ok(new User());
}

这种方式更贴合原生Swagger 2.0规范，但相比前两种方式会稍显繁琐。

注意事项 #

• 如果你使用的是Springfox 3.x及以上版本，将@EnableSwagger2替换为@EnableOpenApi即可，其余配置基本一致。
• 确保参数定义中的paramType、dataType等属性，和控制器方法上的@RequestParam、@PathVariable等注解匹配，保证文档和实际接口的一致性。

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