OpenAPI无法处理具有相同路径的多个控制器方法

我有一个控制器,它有多个具有相同路径的GET端点。唯一的区别是传入该方法的@RequestParam。

这在API中是非常有效和常见的场景。Spring/Java没有抱怨它,OpenAPI也没有;然而,openApi对此解释不正确,此外还有一些其他问题,如下面使用Custom Authentication参数描述的问题。Swagger 2使用了它的一个@ApiParameter注释来处理这个问题。

考虑到Spring、Java、Swagger 2和OpenAPI都没有因此而出错,这个接缝将是OpenAPI的一个相当大的限制,它看起来像一个bug。

下面是我的例子:

    @GetMapping(path = "", params = {"id"}, produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(
        operationId = "getUsersById",
        summary = "Returns all users records with the same id.",
        description = "Retrieves users from persistence storage by given id.",
        tags = {"UserController"},
        parameters = {
            @Parameter(in = ParameterIn.HEADER,
                name = "Custom-Authorization",
                description = "Jwt Bearer Token",
                example = "Bearer eyJhbGciOiJIUzU...",
                required = true,
                schema = @Schema(type = "string"))
        },
        responses = {
            @ApiResponse(
                responseCode = "200",
                description = "Users Json array.",
                content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserResponse.class)))),
            @ApiResponse(
                responseCode = "404",
                description = "User(s) with provided id could not be found.",
                content = @Content(schema = @Schema(implementation = ResponseEntity.class))) 
        })
    public List<UserResponse> getUsersById(
        @Parameter(name = "id", example = "1234567", required = true)
        @RequestParam String id) throws MyException {

        ...
    }

    @GetMapping(path = "", params = {"lastName"}, produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(hidden = true,
        operationId = "getUserByLastName",
        summary = "Returns all user records with the same last name.",
        description = "Retrieves users from persistence storage by given last name.",
        tags = {"UserController"},
//        parameters = {
//            @Parameter(in = ParameterIn.HEADER,
//                name = "Custom-Authorization",
//                description = "Jwt Bearer Token",
//                example = "Bearer eyJhbGciOiJIUzU...",
//                required = true,
//                schema = @Schema(type = "string"))
//        },
        responses = {
            @ApiResponse(
                responseCode = "200",
                description = "Users Json array.",
                content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserResponse.class)))),
            @ApiResponse(
                responseCode = "404",
                description = "Users with provided last name could not be found.",
                content = @Content(schema = @Schema(implementation = ResponseEntity.class))) 
        })
    public List<UserResponse> getUserLastName(
        @Parameter(name = "lastName", example = "Tester", required = true)
        @RequestParam String lastName) throws MyException {
        
        ...
    }

这个问题springdoc/springdoc openapi#580建议使用@Hidden,或者隐藏在其他端点上,因此只显示其中一个端点,这就是我上面所做的;然而,这显然是不正确的,也不是一个好的解决方案。

另一个问题是,我无法为我的自定义授权标头提供参数,所以我不得不在隐藏的端点中对其进行注释;否则,我会遇到类似“重复参数”之类的错误。