Endpoints get merged in Swagger UI when they differ only by query parameters

[jiallombardo]

Steps to reproduce:

1. Define endpoints in controller in the following way:

@Operation(method = "GET", summary = "Api call that's secured, requires IP parameter", security = {@SecurityRequirement(name = "bearer-token")}, operationId = "op1")
    @GetMapping(value = "/v1/api", params = "ip")
    @PreAuthorize("@authorizationService.isAuthorized(#accessToken,#ip)")
public Mono<Payload> getData(@Parameter(description = IP) @RequestParam(IP_PARAMETER) String ip) {
//logic doesn't matter
}
    @Operation(method = "GET", summary = "This API call is not secured, and it requires IP parameter to not be included", security = {@SecurityRequirement(name = "bearer-token")}, operationId = "op2")
    @GetMapping(value = "/v1/api", params = "!ip")
    public Mono<Payload> getData(@Parameter(description = FORM_FACTOR) @RequestParam(required = false)  FormFactor formFactor) {
//logic doesn't matter
}

Note that the two endpoints differ only by parameter usage (the first one requires "ip" to be in the query, whereas the second one requires it to be absent from the query). The two endpoint are separate, since they invoke very different logic, one is secured via @PreAuth and the other is not, and the API user, when viewing docs, should be able to see the distinct difference between them.
The operationId was added in an attempt to force the openAPI engine to distinguish these two endpoints, but it didn't work.

2. Use the following OpenAPI configuration:

@Configuration
public class OpenAPIConfiguration {

    /**
     * Basic openAPI bootstrap bean definition.
     * Run the app and go to host:port/swagger-ui.html to see the generated API docs.
     */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components().addSecuritySchemes("bearer-token", new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")));
    }
}

3. Open swagger-ui.html

Expected result -- the two endpoint will be displayed separately on the UI
Actual result -- only one endpoint (the first one) gets displayed on the UI

Springdoc version used: 1.4.4
Spring-boot version used: 2.1.6

Please advise, if something could be done to circumnavigate this issue.

[bnasslahsen]

@jiallombardo,

For one path / http Method you only get one correspondding path in the OpenAPI description, which is conform to the spec.

If you expect, two different endpoints,you can rename one of your endpoints.

[jiallombardo]

@bnasslahsen , do you mean I should rename paths? E.g. /v1/otherApi? Unfortunately, I can't change paths just to fix documentation.

Also, what spec do you refer to? I just want to understand the spec; perhaps, I can apply some other spec / framework in order to achieve what I want?

[bnasslahsen]

@jiallombardo,

I am refering to the OpenAPI 3 spec.

OpenAPI defines a unique operation as a combination of a path and an HTTP method. This means that two GET or two POST methods for the same path are not allowed – even if they have different parameters (parameters have no effect on uniqueness).

More details can be available here:

• https://swagger.io/docs/specification/paths-and-operations/