Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
sander1095 opened this issue Oct 30, 2024 · 4 comments · May be fixed by #35009
Open

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

sander1095 opened this issue Oct 30, 2024 · 4 comments · May be fixed by #35009
Assignees
@Rick-Anderson
Labels
10.0 .NET 10

Comments

@sander1095
Copy link
Contributor

sander1095 commented Oct 30, 2024 •
edited
Loading

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
@Rick-Anderson Rick-Anderson self-assigned this Oct 30, 2024
@Rick-Anderson
Copy link
Contributor

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

@sander1095
Copy link
Contributor Author

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

@A-Stapleton
Copy link

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

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

@sander1095
Copy link
Contributor Author

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 😄

@sander1095 sander1095 mentioned this issue Feb 18, 2025
Open
@dotnetrepoman dotnetrepoman bot added the mapQuest clean move label Mar 7, 2025
@dotnet-policy-service dotnet-policy-service bot removed the mapQuest clean move label Mar 7, 2025
@Rick-Anderson Rick-Anderson added the 10.0 .NET 10 label Mar 7, 2025
@dotnetrepoman dotnetrepoman bot added the mapQuest clean move label Mar 14, 2025
@dotnet-policy-service dotnet-policy-service bot removed the mapQuest clean move label Mar 14, 2025
@sander1095 sander1095 linked a pull request Mar 19, 2025 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Rick-Anderson Rick-Anderson

Labels
10.0 .NET 10
Projects
dotnet/AspNetCore.Docs March 2025 sprint
Status: 🔖 Ready
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add ProducesResponseType Description documentation sander1095/AspNetCore.Docs
3 participants
@Rick-Anderson @sander1095 @A-Stapleton