OpenAPI Generation No Longer Groups Endpoints Using WithGroupName

[awebre]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

In .NET 9, multiple Open API spec docs could be generated with a specific name utilizing the .WithGroupName extension method on either the group itself or particular endpoints. This allowed for a name other than the group's prefix to be used for grouping endpoints into an OpenAPI document that utilized a name other than the group's route prefix.

Now, it seems that the OpenAPI generator does not group those endpoints into the related spec document and instead excludes them entirely.

Expected Behavior

I should be able to group endpoints in an OpenAPI Spec document named something other than the Group prefix, utilizing .WithGroupName("MyGroupName") and .AddOpenApi("MyGroupName").

Steps To Reproduce

I have a minimal repro solution that demonstrates the behaviors here:
https://github.com/GoValidate/AspNetCore-Net10-OpenApi-Repro

The OpenApiNet9 and OpenApiNet10 are carbon copies of each other, with one targeting .NET 9 (and the .NET 9 version of AspNetCore OpenAPI) and the other targeting .NET 10 (and the .NET 10 version of AspNetCore OpenAPI). The code in both cases is the same:

var builder = WebApplication.CreateBuilder();

const string FirstGroup = "FirstGroup";
const string SecondGroup = "SecondGroup";

builder.Services.AddOpenApi();
builder.Services.AddOpenApi(FirstGroup);
builder.Services.AddOpenApi(SecondGroup);

var app = builder.Build();

app.MapOpenApi();

app.Map("no-group", () => "No group endpoint");
app.MapGroup("/first-group")
    .MapGet("/explicit", () => $".WithGroup(\"{FirstGroup}\") called on this endpoint")
    .WithGroupName(FirstGroup);

app.MapGroup("/second-group")
    .WithGroupName("SecondGroup")
    .MapGet("/implicit", () => $".WithGroup(\"{SecondGroup}\") called on the parent group");

app.Run();

New NET 10 Behavior

The following Open API docs are generated in NET 10:
https://localhost:5001/openapi/FirstGroup.json

{
  "openapi": "3.1.1",
  "info": {
    "title": "OpenApiNet10 | firstgroup",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:5001/"
    }
  ],
  "paths": { }
}

https://localhost:5001/openapi/SecondGroup.json

{
  "openapi": "3.1.1",
  "info": {
    "title": "OpenApiNet10 | secondgroup",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:5001/"
    }
  ],
  "paths": { }
}

Expected Behavior

In OpenApiNet9, the following swagger docs are generated:

https://localhost:7001/openapi/FirstGroup.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenApiNet9 | FirstGroup",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:7001/"
    }
  ],
  "paths": {
    "/first-group/explicit": {
      "get": {
        "tags": [
          "OpenApiNet9"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": { },
  "tags": [
    {
      "name": "OpenApiNet9"
    }
  ]
}

https://localhost:7001/openapi/SecondGroup.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenApiNet9 | SecondGroup",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:7001/"
    }
  ],
  "paths": {
    "/second-group/implicit": {
      "get": {
        "tags": [
          "OpenApiNet9"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": { },
  "tags": [
    {
      "name": "OpenApiNet9"
    }
  ]
}

Exceptions (if any)

No response

.NET Version

10.0.100

Anything else?

IDE is Rider (though this exhibits with dotnet run).

Output from dotnet --info

.NET SDK:
 Version:           10.0.100
 Commit:            b0f34d51fc
 Workload version:  10.0.100-manifests.4c0ca8ba
 MSBuild version:   18.0.2+b0f34d51f

Runtime Environment:
 OS Name:     Mac OS X
 OS Version:  26.1
 OS Platform: Darwin
 RID:         osx-arm64
 Base Path:   /usr/local/share/dotnet/sdk/10.0.100/

.NET workloads installed:
There are no installed workloads to display.
Configured to use workload sets when installing new manifests.
No workload sets are installed. Run "dotnet workload restore" to install a workload set.

Host:
  Version:      10.0.0
  Architecture: arm64
  Commit:       b0f34d51fc

.NET SDKs installed:
  6.0.425 [/usr/local/share/dotnet/sdk]
  7.0.317 [/usr/local/share/dotnet/sdk]
  8.0.402 [/usr/local/share/dotnet/sdk]
  9.0.100-rc.2.24474.11 [/usr/local/share/dotnet/sdk]
  9.0.100 [/usr/local/share/dotnet/sdk]
  9.0.200 [/usr/local/share/dotnet/sdk]
  10.0.100 [/usr/local/share/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 6.0.33 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 7.0.20 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.8 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.0-rc.2.24474.3 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.2 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 10.0.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.33 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 7.0.20 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.8 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.0-rc.2.24473.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.2 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 10.0.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
  None

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

[desjoerd]

Took some debugging and looking into the solution.
It seems there is a regression regarding casing of group names. If you update your groups to be lowercase it will work.

It's because of a mismatch in the default OpenApiOptions.ShouldInclude and the registration of the document with the DocumentName

    public OpenApiOptions()
    {
        ShouldInclude = (description) => description.GroupName == null || description.GroupName == DocumentName;
    }

    public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName, Action<OpenApiOptions> configureOptions)
    {
        ArgumentNullException.ThrowIfNull(services);
        ArgumentNullException.ThrowIfNull(configureOptions);

        // We need to register the document name in a case-insensitive manner to support case-insensitive document name resolution.
        // The document name is used to store and retrieve keyed services and configuration options, which are all case-sensitive.
        // To achieve parity with ASP.NET Core routing, which is case-insensitive, we need to ensure the document name is lowercased.
        var lowercasedDocumentName = documentName.ToLowerInvariant();

        services.AddOpenApiCore(lowercasedDocumentName);
        services.Configure<OpenApiOptions>(lowercasedDocumentName, options =>
        {
            options.DocumentName = lowercasedDocumentName;
            configureOptions(options);
        });
        return services;
    }

The default ShouldInclude is case senitive. But when adding the document it will register the document name as lowercase.

Following workarounds:

1. Update the group names to be lowercase

2. Patch the ShouldInclude for the OpenApi document registration

builder.Services.AddOpenApi(FirstGroup, options =>
{
    options.ShouldInclude = (description) => description.GroupName == null
                                             || string.Equals(description.GroupName, options.DocumentName, StringComparison.InvariantCultureIgnoreCase);
});

3. Patch for all

builder.Services.ConfigureAll((OpenApiOptions options) =>
{
    options.ShouldInclude = (description) => description.GroupName == null
                                             || string.Equals(description.GroupName, options.DocumentName, StringComparison.InvariantCultureIgnoreCase);
});

[awebre]

Thanks for the quick response! Looks like this was absolutely it. In our case we have multiple documents that we are generating so ConfigureAll made the most sense to restore the behavior we were expecting.

[captainsafia]

@desjoerd Thanks for digging into this! I'm bummed that we didn't have the test coverage to catch this. I'll work on merging a fix in for .NET 11 and keep this open to gauge whether or not we take this through servicing.

[desjoerd]

@captainsafia I've got some time tomorrow, so could put in a PR for this, with some test coverage.

Edit, I see you assigned Copilot, so that would probably cover it 😁