docs: prevent collision in operation names in IdentityHub management API

[bscholtes1A]

What this PR changes/adds

Prevent API operation name collision in merged OpenAPI file for Management API.

Why it does that

Some API Gateway such as Azure API Management does not support multiple API operations having the same name in the same openapi file.

Further notes

List other areas of code that have changed but are not necessarily linked to the main feature. This could be method
signature changes, package declarations, bugs that were encountered and were fixed inline, etc.

Linked Issue(s)

Closes # <-- insert Issue number if one exists

Please be sure to take a look at the contributing guidelines and our etiquette for pull requests.

[paullatzelsperger]

I am OK with renaming method names, but I think the better approach here is to explicitly set the operationId on OpenApi annotations like so:

    @Tag(name = "KeyPairResources Management API")
    @Operation(description = "Finds a KeyPairResource by ID.",
            operationId = "findKeyPairResourceById", <-- ADD THIS
            responses = {
                    // responses
            }
    )
    KeyPairResource findById(String id, SecurityContext securityContext);

That way we can decouple method names from the API spec and we prevent subtle bugs in the future, that no-one detects until the API is actually published using Azure API GW.

We should do both, the method renaming and the explicit declaration.

[bscholtes1A]

I am OK with renaming method names, but I think the better approach here is to explicitly set the operationId on OpenApi annotations like so:

    @Tag(name = "KeyPairResources Management API")
    @Operation(description = "Finds a KeyPairResource by ID.",
            operationId = "findKeyPairResourceById", <-- ADD THIS
            responses = {
                    // responses
            }
    )
    KeyPairResource findById(String id, SecurityContext securityContext);

That way we can decouple method names from the API spec and we prevent subtle bugs in the future, that no-one detects until the API is actually published using Azure API GW.

We should do both, the method renaming and the explicit declaration.

updated