[Feature Request] Please support the API of different headers with the same path

[yihleego]

Is your feature request related to a problem? Please describe.

I want to use the same path to route to different methods by passing specified headers values, plz see the example:

@PutMapping(value = "password", headers = "Verification-Type=VERIFICATION_CODE")
public Result<Void> updatePassword(@RequestBody PasswordVerificationCodeParam param) {
    // Code here...
}

@PutMapping(value = "password", headers = "Verification-Type=EMAIL_CREDENTIALS")
public Result<Void> updatePassword(@RequestBody PasswordEmailCredentialsParam param) {
    // Code here...
}

public class PasswordVerificationCodeParam {
    private String phone;
    private String code;
    private String newPassword;
    // ignored
}

public class PasswordEmailCredentialsParam {
    private String credentials;
    private String newPassword;
    // ignored
}

And this feature is not yet supported:

java.lang.IllegalStateException: Duplicate key class Parameter {
    name: Verification-Type
    in: header
    description: null
    required: null
    deprecated: null
    allowEmptyValue: null
    style: null
    explode: null
    allowReserved: null
    schema: class StringSchema {
        class Schema {
            type: string
            format: null
            $ref: null
            description: null
            title: null
            multipleOf: null
            maximum: null
            exclusiveMaximum: null
            minimum: null
            exclusiveMinimum: null
            maxLength: null
            minLength: null
            pattern: null
            maxItems: null
            minItems: null
            uniqueItems: null
            maxProperties: null
            minProperties: null
            required: null
            not: null
            properties: null
            additionalProperties: null
            nullable: null
            readOnly: null
            writeOnly: null
            example: null
            externalDocs: null
            deprecated: null
            discriminator: null
            xml: null
        }
    }
    examples: null
    example: null
    content: null
    $ref: null
}
	at org.springdoc.core.AbstractRequestService.lambda$getParameterLinkedHashMap$5(AbstractRequestService.java:295) ~[springdoc-openapi-common-1.5.6.jar:1.5.6]
	at java.base/java.util.HashMap.merge(HashMap.java:1387) ~[na:na]

Version:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.6</version>
</dependency>

Describe the solution you'd like

It is expected that there will be two operations with the same path,
or users could select the options to switch the values.

Thanks❤

[bnasslahsen]

@yihleego,

Please see my answer on the reason, we have no rule for supporting this out of the box: #580.
The straightforward solution is to use @Operation annotation as suggested.

Alternatively, you can define two different groups: For each one you filter using header matching, option headersToMatch of GroupedOpenApi Bean.