Incorrect OpenApi documentation in Minimal API when using WithOpenApi extension method

[marcominerva]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I'm using .NET 7.0. I have created a Minimal API with the following endpoint:

app.MapDelete("api/people/{id:int}", Results<NoContent, NotFound> (int id) =>
{
    return id > 0 ? TypedResults.NoContent() : TypedResults.NotFound();
});

This produces the following page in Swagger:

In particular, the description of the 404 response is correctly "Not Found".

However, if I add the WithOpenApi extension method to the endpoint, like this:

app.MapDelete("api/people/{id:int}", Results<NoContent, NotFound> (int id) =>
{
    return id > 0 ? TypedResults.NoContent() : TypedResults.NotFound();
})
.WithOpenApi(operation =>
{
    operation.Summary = "Deletes a person given the ID";
    operation.Description = "If the person does not exist, a 404 response is returned";
    return operation;
});

I obtain this:

So, the 404 response now has the description "Client error", which is incorrect.

Expected Behavior

The description of 404 response should be "Not Found" even when I use the WithOpenApi extension method.

Steps To Reproduce

Minimal repro here: https://github.com/marcominerva/OpenApiIssue.

Exceptions (if any)

No response

.NET Version

7.0.100

Anything else?

Visual Studio 2022 17.4.1

.NET SDK:
Version: 7.0.100
Commit: e12b7af219

Ambiente di runtime:
OS Name: Windows
OS Version: 10.0.22621
OS Platform: Windows
RID: win10-x64
Base Path: C:\Program Files\dotnet\sdk\7.0.100\

Host:
Version: 7.0.0
Architecture: x64
Commit: d099f075e4

.NET SDKs installed:
7.0.100 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
Microsoft.AspNetCore.All 2.1.13 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
Microsoft.AspNetCore.App 2.1.13 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 3.1.31 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 5.0.17 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 6.0.11 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 7.0.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 2.1.13 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 3.1.31 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 5.0.17 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 6.0.9 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 6.0.10 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 6.0.11 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 7.0.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 3.1.31 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 5.0.17 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 6.0.9 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 6.0.10 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 6.0.11 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 7.0.0 [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

[captainsafia]

@marcominerva Thanks for filing this issue! Good spot.

The reason that his happens is that when calling the WithOpenApi method, the generated status code descriptions are produced from this codepath.

aspnetcore/src/OpenApi/src/OpenApiGenerator.cs

Lines 215 to 231 in 51e4382

	private static string GetResponseDescription(string statusCode)
	{
	if (statusCode.Length != 3)
	{
	return string.Empty;
	}
	var first = statusCode[0];
	return first switch
	{
	'1' => "Information",
	'2' => "Success",
	'3' => "Redirection",
	'4' => "Client error",
	'5' => "Server error",
	_ => string.Empty,
	};
	}

Whereas the default scenario goes through the generator in whatever package you are using (usually Swashbuckle or NSwag).

Would you be interested in updating the code above to include handling for 404?

[marcominerva]

Hi @captainsafia, thank you for your answer!

Yes, I will be happy to contribute! What do you think about just returning the reason phrase that corresponds to the status code? It could be a good solution?

[captainsafia]

Yes, I will be happy to contribute! What do you think about just returning the reason phrase that corresponds to the status code? It could be a good solution?

Great! The reason code sounds good. The one small challenge we ran into when implementing this is exactly which status codes to support. 404 is an obvious miss but I think giving more specific status codes for the most common status codes (401 as unauthorized) is sensible.

BTW, as a workaround for the original issue, you can set the status code yourself via:

app.MapGet("/", () => ...)
  .WithOpenApi(o => new(o)
  {
    o.Responses["404"].Description = "Not found";
  })

[marcominerva]

Thank you for the workaround, I'll try to make a PR with the fix as soon as possible!