OpenAPI cannot handle multiple controller methods with same path

[dbnex14]

I have Controller with multiple GET endpoints having same path. The only difference is the @RequestParam passed into the method.

This is perfectly valid and common scenario in APIs. Spring / Java does not complain about it, nor does OpenAPI; however, openApi interprets this incorrectly in addition to some other issues like described below with the Custom-Authentication parameter. Swagger 2 was handling this fine with the use of one of its @ApiParameter annotations.

Given that neither Spring, nor Java, nor Swagger 2, nor OpenAPI error out because of this, this seam to be a quite limitation of OpenAPI and it looks like a bug.

Here is my example:

    @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 {
        
        ...
    }

This issue https://github.com/springdoc/springdoc-openapi/issues/580 suggests using @Hidden, or hidden on others endpoint and therefore showing only one of them which is what I did above; however, this is obviously incorrect and not a good solution.

The other issue is that I cannot provide parameter for my Custom-Authorization header, so I had to comment it in the hidden endpoints; otherwise, I get error like "duplicate parameter" or something along the way.

[nik-frolkov]

I agree. this functionality will be useful

[Yandimirov]

I faced with the same issue. And I also think that this functionality is very helpful.

[MikeRalphson]

Please raise tooling-related issues on the relevant repository. This repository is for the OpenAPI specification itself which has no direct notion of controllers or their methods. You may also receive more answers on a general support forum such as StackOverflow. Thanks.