OpenApi: Lowercase document name on registration to match AddOpenApi internal behaviour (closes #23210)

[lauraneto]

Prerequisites

• I have added steps to test this contribution in the description below

If there's an existing issue for this PR then this fixes #23210

Description

AddOpenApi (from Microsoft.AspNetCore.OpenApi) lowercases the document name internally when registering its keyed services. ReplaceOpenApiSchemaService then searches for the keyed OpenApiSchemaService registration using the name as passed — so if the name contains uppercase letters the lookup fails with an InvalidOperationException.

Both BackOfficeOpenApiDocumentBuilder.Build() and AddUmbracoOpenApiDocument now normalise the name to lowercase for DI registration calls (AddOpenApi, AddOpenApiDocumentToUi, ReplaceOpenApiSchemaService). The original name is preserved where it is used for endpoint filtering — HasMapToApiAttribute in BackOfficeOpenApiDocumentBuilder and ApiName in ConfigureUmbracoOpenApiOptionsBase subclasses — so [MapToApi] attribute matching continues to work correctly.

Testing

Add a sample constants file:

internal static class ExampleApiConstants
{
    // Mixed-case name intentionally used to exercise the AddOpenApi lowercasing behaviour.
    internal const string ApiName = "MyExtensionApi";
}

Add a sample controller:

[ApiController]
[ApiVersion("1.0")]
[BackOfficeRoute("example/api/v{version:apiVersion}")]
[MapToApi(ExampleApiConstants.ApiName)]
public class ExampleApiController : ControllerBase
{
    [HttpGet("ping")]
    [ProducesResponseType<string>(StatusCodes.Status200OK)]
    public string Ping() => "Pong";
}

Add a sample composer registering :

public class ExampleApiComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder) =>
        builder.AddBackOfficeOpenApiDocument(
            ExampleApiConstants.ApiName,
            document => document
                .WithTitle("Example API")
                .WithJsonOptions(Umbraco.Cms.Core.Constants.JsonOptionsNames.BackOffice));
}

Start the application. Before this fix it throws InvalidOperationException at startup. After the fix the application starts and the document is available at /umbraco/openapi/mydocument.json.
Also verify that the Management and DeliveryAPI open api documents are still accessible and including the respective endpoints.

[claude]

Claude finished @lauraneto's task in 4m 8s —— View job

---

PR Review

Target: origin/main · Based on commit: b894f500

Normalises the OpenAPI document name to lowercase before all DI registration calls (AddOpenApi, AddOpenApiDocumentToUi, ReplaceOpenApiSchemaService), matching the internal behaviour of Microsoft.AspNetCore.OpenApi which lowercases the name when keying its services. The original mixed-case name is preserved solely for [MapToApi] attribute matching in ShouldInclude.

---

Important

• src/Umbraco.Cms.Api.Common/OpenApi/BackOfficeOpenApiDocumentBuilder.cs:120: No regression test covers the specific bug scenario — a mixed-case document name combined with WithJsonOptions causing startup to throw InvalidOperationException. The existing integration tests (BackOfficeOpenApiDocumentWithJsonOptionsTests) use "test-with-json-options" (already lowercase) and would pass both before and after the fix, proving nothing about the case-sensitivity issue. Per the repo testing policy, a bug-fix test must fail without the fix. Adding a subclass with ApiName = "TestWithJsonOptions" (mixed-case) would create an honest regression guard. Fix this →

---

Approved with Suggestions for improvement

The fix is correct and minimal — the split between registrationName (lowercase, for DI) and DocumentName (original case, for [MapToApi] matching) is exactly the right approach, and the comment in Build() explains the non-obvious constraint well. The same pattern is consistently applied in AddUmbracoOpenApiDocument. Good to go, but please consider adding the missing regression test before merging.

[Copilot]

Pull request overview

This PR fixes a startup failure when registering OpenAPI documents with mixed-case names by normalizing the document name to lowercase for DI registration, aligning Umbraco’s registrations with Microsoft.AspNetCore.OpenApi’s internal lowercasing behavior.

Changes:

• Normalize BackOfficeOpenApiDocumentBuilder’s DI registration key to DocumentName.ToLowerInvariant() while preserving the original DocumentName for [MapToApi] endpoint filtering.
• Normalize AddUmbracoOpenApiDocument’s apiName to lowercase before calling AddOpenApi, UI registration, and schema-service replacement.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/Umbraco.Cms.Api.Common/OpenApi/BackOfficeOpenApiDocumentBuilder.cs	Lowercases the OpenAPI document registration key to keep AddOpenApi, UI registration, and schema-service replacement keyed consistently.
src/Umbraco.Cms.Api.Common/DependencyInjection/UmbracoBuilderApiExtensions.cs	Lowercases apiName before OpenAPI registration to match keyed service behavior.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
83.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[kjac]

Works like a charm, and I can reproduce the issue on main 👍