MinimalApis using MapGroup are not exposed by the .NET 9 WithOpenApi method

[shawnwildermuth]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When I create a Minimal API and use WithOpenApi(), it works fine:

    app.MapGet("api/years", GetYears)
      .Produces<int[]>()
      .Produces<string[]>(200)
      .ProducesProblem(500)
      .WithOpenApi();

But if I use MapGroup() it doesn't get generated:

    var group = app.MapGroup("/api/films")
      .WithGroupName("Film Apis");

    group.MapGet("api/years", GetYears)
      .Produces<int[]>()
      .Produces<string[]>(200)
      .ProducesProblem(500)
      .WithOpenApi();

If I remove the MapGroup, it works fine.

Expected Behavior

Should expose the API through the OpenAPI spec. Works without groups.

Steps To Reproduce

https://github.com/shawnwildermuth/BechdelDataServer/tree/net9

Exceptions (if any)

None.

.NET Version

9.0.100-preview.5.24307.3

Anything else?

.NET SDK:
Version: 9.0.100-preview.5.24307.3
Commit: 35b2c21ea6
Workload version: 9.0.100-manifests.6407b7e4
MSBuild version: 17.11.0-preview-24279-02+b963c24ef

Runtime Environment:
OS Name: Windows
OS Version: 10.0.22631
OS Platform: Windows
RID: win-x64
Base Path: C:\Program Files\dotnet\sdk\9.0.100-preview.5.24307.3\

.NET workloads installed:
Configured to use loose manifests when installing new manifests.
[aspire]
Installation Source: VS 17.10.35013.160, VS 17.11.35017.193
Manifest Version: 9.0.0-preview.2.24163.9/9.0.100-preview.1
Manifest Path: C:\Program Files\dotnet\sdk-manifests\9.0.100-preview.1\microsoft.net.sdk.aspire\9.0.0-preview.2.24163.9\WorkloadManifest.json
Install Type: Msi

[ios]
Installation Source: VS 17.10.35013.160
Manifest Version: 17.2.9088-net9-p1/9.0.100-preview.1
Manifest Path: C:\Program Files\dotnet\sdk-manifests\9.0.100-preview.1\microsoft.net.sdk.ios\17.2.9088-net9-p1\WorkloadManifest.json
Install Type: Msi

[maccatalyst]
Installation Source: VS 17.10.35013.160
Manifest Version: 17.2.9088-net9-p1/9.0.100-preview.1
Manifest Path: C:\Program Files\dotnet\sdk-manifests\9.0.100-preview.1\microsoft.net.sdk.maccatalyst\17.2.9088-net9-p1\WorkloadManifest.json
Install Type: Msi

[android]
Installation Source: VS 17.10.35013.160
Manifest Version: 34.99.0-preview.1.151/9.0.100-preview.1
Manifest Path: C:\Program Files\dotnet\sdk-manifests\9.0.100-preview.1\microsoft.net.sdk.android\34.99.0-preview.1.151\WorkloadManifest.json
Install Type: Msi

[maui-windows]
Installation Source: VS 17.10.35013.160
Manifest Version: 9.0.0-preview.1.9973/9.0.100-preview.1
Manifest Path: C:\Program Files\dotnet\sdk-manifests\9.0.100-preview.1\microsoft.net.sdk.maui\9.0.0-preview.1.9973\WorkloadManifest.json
Install Type: Msi

Host:
Version: 9.0.0-preview.5.24306.7
Architecture: x64
Commit: a5cc707d97

.NET SDKs installed:
5.0.408 [C:\Program Files\dotnet\sdk]
6.0.423 [C:\Program Files\dotnet\sdk]
7.0.410 [C:\Program Files\dotnet\sdk]
8.0.206 [C:\Program Files\dotnet\sdk]
8.0.300 [C:\Program Files\dotnet\sdk]
8.0.301 [C:\Program Files\dotnet\sdk]
8.0.302 [C:\Program Files\dotnet\sdk]
9.0.100-preview.5.24307.3 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
Microsoft.AspNetCore.App 5.0.17 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 6.0.31 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 7.0.20 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 8.0.5 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 8.0.6 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 9.0.0-preview.5.24306.11 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 5.0.17 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 6.0.31 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 7.0.20 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 8.0.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 8.0.6 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 9.0.0-preview.5.24306.7 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 5.0.17 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 6.0.31 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 7.0.20 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 8.0.5 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 8.0.6 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 9.0.0-preview.5.24306.8 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
x86 [C:\Program Files (x86)\dotnet]
registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
Not set

global.json file:
Not found

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

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

[martincostello]

Are your groups/paths configured correctly?

IIRC, this:

var group = app.MapGroup("/api/films")
               .WithGroupName("Film Apis");

group.MapGet("api/years", ...);

would translate to a URL of /api/films/api/years, which doesn't seem what's intended to me.

If you change the MapGet() to years (which should yield /api/films/years) does the operation appear in the OpenAPI document then?

[shawnwildermuth]

Are your groups/paths configured correctly?

IIRC, this:

var group = app.MapGroup("/api/films")
               .WithGroupName("Film Apis");

group.MapGet("api/years", ...);

would translate to a URL of /api/films/api/years, which doesn't seem what's intended to me.

If you change the MapGet() to years (which should yield /api/films/years) does the operation appear in the OpenAPI document then?

That isn't the issue (I think), i'll make the change to the repo just in case, but even if the endpoint address was wrong, it would still not generate the group (and its endpoints) to the OpenAPI document. Did you see this differently? (Maybe you're on a later preview that isn't public?)

[martincostello]

I only took a quick look at the repro to start with. I figured if it was wrong, better to fix it before digging into anything in case it happened to be the cause.

[shawnwildermuth]

I only took a quick look at the repro to start with. I figured if it was wrong, better to fix it before digging into anything in case it happened to be the cause.

I appreciate it.

[captainsafia]

Chiming in on some thoughts here:

When it comes to the new OpenAPI support in Microsoft.AspNetCore.OpenApi, WithOpenApi is no longer a relevant API. I added some docs around this in 5f8f891. Let me know if they can be clearer.

@martincostello and I had a brief discussion on the future of WithOpenApi and OpenApiOperation metadata in this issue (domaindrivendev/Swashbuckle.AspNetCore#2849). It hopefully gives some context into what WithOpenApi was doing and where it will go moving forward. Feel free to chime in with your thoughts there.

With that in mind, for .NET 9, all the WithOpenApi calls that you have in your code are effectively inert when used in conjunction with built-in OpenAPI support and can be removed with no impact.

I cloned your repo locally, checked out the net9 branch, and upgraded to the last nightly build of the Microsoft.AspNetCore.OpenApi package. From there, I observed that the only endpoint represented in the OpenAPI document was the /api/years one, similar to your original bug report.

I suspect the issue here is actually with the WithGroupName invocation and not MapGroup itself. When I comment out the WithGroupName invocation like so, I see all the endpoints.

    var group = app.MapGroup("/api/films");
      // .WithGroupName("Film Apis");

The reason this happens is because of the way both Swashbuckle and M.A.OpenApi react to the way ApiExplorer aggregates endpoints into an application in groups. The TL;DR is that group names map to document names in both universes. So when you have something like:

    var group = app.MapGroup("/api/films");
      .WithGroupName("film-apis");

You'll need:

builder.Services.AddOpenApi("film-apis");

And you'll need to access the document at https://localhost:8080/spec/bechdel.json?documentName=film-apis or use the default OpenAPI route and visit https://localhost:8080/openapi/film-apis.json.

- app.MapOpenApi("/spec/bechdel.json");
+ app.MapOpenApi();

We cover some of this in our new docs page here and here. However, I realize we can do a way better job of clarifying the relationship between document names and group names.

Hope this is helpful info and apologies for the delay as I work through the backlog of issues here. 😅

[dotnet-policy-service]

This issue has been resolved and has not had any activity for 1 day. It will be closed for housekeeping purposes.

See our Issue Management Policies for more information.