-
Notifications
You must be signed in to change notification settings - Fork 25.3k
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.
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
Add Web API controller action return types doc #5750
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Outstanding!
|
||
The [IActionResult](/dotnet/api/microsoft.aspnetcore.mvc.iactionresult) return type is appropriate when multiple [ActionResult](/dotnet/api/microsoft.aspnetcore.mvc.actionresult) return types are possible in an action. The `ActionResult` types represent various HTTP status codes. Some common return types falling into this category are [BadRequestResult](/dotnet/api/microsoft.aspnetcore.mvc.badrequestresult) (400), [NotFoundResult](/dotnet/api/microsoft.aspnetcore.mvc.notfoundresult) (404), and [OkObjectResult](/dotnet/api/microsoft.aspnetcore.mvc.okobjectresult) (200). | ||
|
||
Because there are multiple return types and paths in the action, liberal use of the [[ProducesResponseType]](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute.-ctor) attribute is necessary. This attribute produces more descriptive response details for API help pages generated by tools like [Swagger](/aspnet/core/tutorials/web-api-help-pages-using-swagger). It indicates the known types and HTTP status codes to be returned by the action. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ProducesResponseType
It indicates the known types and HTTP status codes to be returned by the action.
|
||
## ActionResult\<T> type | ||
|
||
ASP.NET Core 2.1 introduces `ActionResult<T>` as a valid return type in Web API controller actions. It enables you to return a type deriving from [ActionResult](/dotnet/api/microsoft.aspnetcore.mvc.actionresult) or return a [specific type](#specific-type). `ActionResult<T>` offers the following benefits over the [IActionResult type](#iactionresult-type): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
valid
maybe something like
ASP.NET Core 2.1 introduces the ActionResult<T>
return type for Web API controller actions.
|
||
[!code-csharp[](../web-api/action-return-types/samples/WebApiSample.Api.21/Controllers/ProductsController.cs?name=snippet_GetById&highlight=8,11)] | ||
|
||
In the preceding code snippet, a 404 status code is returned when the product doesn't exist in the database. If the product does exist, the corresponding `Product` object is returned. Before ASP.NET Core 2.1, the `return product;` line would have been `return Ok(product);`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
n the preceding code snippet,
* Add Web API controller action return types doc (#5750) * Add Web API controller action return types doc * Verbiage tweaks * Verbiage clarification * Rename action and add a tip widget * Tweak verbiage in tip widget * Add another tip widget * More verbiage changes * MOAR tweaks! * Expand description in specific type section * Fix invalid OkObjectResult syntax * Address Acrolinx feedback * Add Web API TOC node and README.md file to samples folder * React to feedback * Upgrade to latest Microsoft.AspNetCore.All and NSwag.AspNetCore (#5774)
Fixes #5698
Addresses #5401
Internal Review Page
This PR adds a new doc providing guidance on Web API controller action return types. The PR also introduces a new top-level "Web API" TOC node.