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.

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

Merged
merged 13 commits into from
Mar 22, 2018

Conversation

scottaddie
Copy link
Member

@scottaddie scottaddie commented Mar 20, 2018

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.

@scottaddie scottaddie added the WIP label Mar 20, 2018
@scottaddie scottaddie changed the title [WIP] Add Web API controller action return types doc Add Web API controller action return types doc Mar 21, 2018
@scottaddie scottaddie removed the WIP label Mar 21, 2018
Copy link
Contributor

@Rick-Anderson Rick-Anderson left a 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.
Copy link
Contributor

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):
Copy link
Contributor

@Rick-Anderson Rick-Anderson Mar 22, 2018

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);`.
Copy link
Contributor

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,

@scottaddie scottaddie merged commit 88bf955 into master Mar 22, 2018
@scottaddie scottaddie deleted the scottaddie/action-result-t branch March 22, 2018 02:41
scottaddie added a commit that referenced this pull request Mar 22, 2018
* 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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants