OpenAPI response descriptions can be set using ProducesResponseType in .NET 10

[sander1095]

Description

The document says:

OpenAPI supports providing a description of the responses returned from an API. ASP.NET Core provides several strategies for setting the response metadata of an endpoint. Response metadata that can be set includes the status code, the type of the response body, and content type(s) of a response. Responses in OpenAPI may have additional metadata, such as description, headers, links, and examples. This additional metadata can be set with a document transformer or operation transformer.

This is true for .NET 9, but for .NET 10 I've implemented dotnet/aspnetcore#55656 which allows a developer to set the response description for both controllers and minimal API like so:

Controllers:

[HttpGet("{id:int:min(1)}")]
[ProducesResponseType<Talk>(StatusCodes.Status200OK, Description = "A talk entity when the request is succesful")]
[ProducesResponseType(StatusCodes.Status422UnprocessableEntity, Description = "The entity is unprocessable SOME_REASON_HERE")]
[ProducesDefaultResponseType(Description = "The response for all other errors that might be thrown")]
public ActionResult<Talk> GetTalk(int id)
{
    // Code here
}

Minimal API:

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
});

The page should be updated to reflect these new possibilities.

This is only relevant for .NET 10, but I thought it'd be worth creating this issue already so it can be tracked!

PS: I'm currently working on creating an API proposal for dotnet/aspnetcore#57963 which might then also add other options for minimal API's in .NET 10: dotnet/aspnetcore#58724

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-9.0&tabs=visual-studio%2Cminimal-apis

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

Document ID

27bad30c-e0b4-10fb-b202-a29d4f8fad24

Article author

@captainsafia

---

Associated WorkItem - 422233

[Rick-Anderson]

@sander1095 Thanks for creating this tracking issue. This is very cool and will be well received I'm sure.

[sander1095]

Thanks @Rick-Anderson ! Thanks so much for that nice comment!

[A-Stapleton]

Can/will this work with the extension methods as well? eg.

builder.MapPost("/", X())
    .Produces("description here");

[sander1095]

Hi @A-Stapleton ! Thanks for your question.

I created dotnet/aspnetcore#58724 for this, but this likely won't be implemented at this moment, based on my discuss with @captainsafia . As I understand it, the team's vision is to use transformers instead which will reduce coupling between your endpoints and OpenAPI metadata. dotnet/aspnetcore#59180 was created to make transformers more easy to use for specific endpoints, which can result in a similar looking result compared to Produces for setting response descriptions.

So, what can you do at this moment? Well:

• You can use [ProducesResponseType], which I mentioned in this issue description
• You can create an OpenAPI transformer (In .NET 9) to loop through operations and http status codes to set them
• You can use @martincostello 's fantastic library https://github.com/martincostello/openapi-extensions , which is way less cumbersome than the 2nd method above :)

If you would still like to be able to use an overload in the Produces method, let your voice be heard in dotnet/aspnetcore#58724 😄