Doc updates for Web API features in .NET 10 Preview 1

[mikekistler]

A number of features have been introduced for ASP.NET Core Web API applications in .NET 10 preview1. The .NET 10 preview docs should be updated with information on these features.

The features to be added are

• OpenAPI 3.1 support
• OpenAPI in Yaml
• Response description on ProducesResponseType
• Better support for testing apps with top-level statements

I created an aspnet-whats-new repo and put examples and descriptions of the .NET 10 preview 1 features in the dotnet-10-preview1 branch.

• OpenAPI 3.1 support OpenApi 3.1 /1 #35242
• OpenAPI in Yaml YAML in OpenAPI #35247
• Response description on ProducesResponseType Add ProducesResponseType Description documentation #35009
• Better support for testing apps with top-level statements Upgraded integration tests to .NET 10 #35033

---

Associated WorkItem - 411595

[sander1095]

Hi @mikekistler ! I created the proposal and PR for the Description on ProducesResponseType.

I want to add 2 things:

ProducesResponseType on Minimal API

Your example branch only shows the ProducesResponseType with a Description being used on a Controller. I would like to suggest that we also showcase this working on Minimal API's:

builder.MapGet("/api/todos",
[ProducesResponseType(typeof(Todo), StatusCodes,Status200Ok, Description = "A list of todo items")]
[ProducesResponseType(StatusCodes.Status400BadRequest, Description = "Some bad request description")]
() =>
{ 
    // Code here
});

I believe this is quite important, as there is currently no way to do this in Minimal API's, unless you're using an OpenAPI transformer, which is more of a hassle than using the attribute approach as they are currently global.

I'm planning on creating a nuget package with transformer extensions for this so it becomes more even easier than the attribute, but that's not relevant for now :)

PS: There was already a discussion on docs for the new ProducesResponseType. I'm linking it so it can be closed later: #33974

ProducesResponseType on ProducesDefault

[ProducesDefaultResponseType] also supports a description. I think it might be worth showcasing this in the docs or release notes, as it can be powerful way to explain to people what the "default" might mean for a (specific) operation.

---

I'm very excited to have been able to add features to ASP.NET Core's OpenAPI module in .NET 10, so let me know if I can help out with docs or other things, still! :)

[mikekistler]

@sander1095 Agreed that we should include an example of adding a description to a response with ProducesResponseType in a minimal API. I'll add an example for that in my repo. Thanks for this suggestion.

[mikekistler]

Hi @Rick-Anderson, based on the recent doc-owners list I think this one should go to you.