From ed5cb3fee7fff35f5f6eebac9d2da42d43203235 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Fri, 21 Oct 2022 16:34:23 -0700 Subject: [PATCH 1/5] mult result types --- aspnetcore/fundamentals/minimal-apis/openapi.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/aspnetcore/fundamentals/minimal-apis/openapi.md b/aspnetcore/fundamentals/minimal-apis/openapi.md index e5b4b5381398..8ba679cddb53 100644 --- a/aspnetcore/fundamentals/minimal-apis/openapi.md +++ b/aspnetcore/fundamentals/minimal-apis/openapi.md @@ -198,6 +198,20 @@ When setting the response type for endpoints that may return a ProblemDetails re When there are no explicit annotations provided by one of the strategies above, the framework attempts to determine a default response type by examining the signature of the response. This default response is populated under the `200` status code in the OpenAPI definition. +### Multiple response types + +If an endpoint can return different response types in different scenarios, you can provide metadata in the following ways: + +* Call the [`Produces`](/dotnet/api/microsoft.aspnetcore.http.openapiroutehandlerbuilderextensions.produces) extension method multiple times, as shown in the following example: + + [!code-csharp[](samples/todo/Program.cs?name=snippet_getCustom)] + +* Use [`Results`](xref:Microsoft.AspNetCore.Http.HttpResults.Results%606) in the signature, as shown in the following example: + + :::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/minimal-apis/samples/MultipleResultTypes/Program.cs" id="snippet_multiple_result_types"::: + + The `Results` union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error. + ## Describe request body and parameters In addition to describing the types that are returned by an endpoint, OpenAPI also supports annotating the inputs that are consumed by an API. These inputs fall into two categories: From c448c611a202ac8f9d1c74239e4994f5027da463 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Fri, 21 Oct 2022 17:06:16 -0700 Subject: [PATCH 2/5] added explanatory text --- aspnetcore/fundamentals/minimal-apis/openapi.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/minimal-apis/openapi.md b/aspnetcore/fundamentals/minimal-apis/openapi.md index 8ba679cddb53..324a7ce4b9fb 100644 --- a/aspnetcore/fundamentals/minimal-apis/openapi.md +++ b/aspnetcore/fundamentals/minimal-apis/openapi.md @@ -206,11 +206,13 @@ If an endpoint can return different response types in different scenarios, you c [!code-csharp[](samples/todo/Program.cs?name=snippet_getCustom)] -* Use [`Results`](xref:Microsoft.AspNetCore.Http.HttpResults.Results%606) in the signature, as shown in the following example: +* Use [`Results`](xref:Microsoft.AspNetCore.Http.HttpResults.Results%606) in the signature and [`TypedResults`](/dotnet/api/microsoft.aspnetcore.http.typedresults) in the body of the handler, as shown in the following example: :::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/minimal-apis/samples/MultipleResultTypes/Program.cs" id="snippet_multiple_result_types"::: - The `Results` union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error. + The `Results` union types declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata, + + The union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error. ## Describe request body and parameters From 4faf01bad9369bc2a98032f53475ad2544ee26c9 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Fri, 21 Oct 2022 17:12:20 -0700 Subject: [PATCH 3/5] fix typo --- aspnetcore/fundamentals/minimal-apis/openapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/minimal-apis/openapi.md b/aspnetcore/fundamentals/minimal-apis/openapi.md index 324a7ce4b9fb..ad62e5c5a5f1 100644 --- a/aspnetcore/fundamentals/minimal-apis/openapi.md +++ b/aspnetcore/fundamentals/minimal-apis/openapi.md @@ -210,7 +210,7 @@ If an endpoint can return different response types in different scenarios, you c :::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/minimal-apis/samples/MultipleResultTypes/Program.cs" id="snippet_multiple_result_types"::: - The `Results` union types declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata, + The `Results` union types declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata. The union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error. From 0d0f6e232985641f714670f2573bef4fcaeb4d5f Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Mon, 24 Oct 2022 13:27:03 -0700 Subject: [PATCH 4/5] add italics --- aspnetcore/fundamentals/minimal-apis/openapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/minimal-apis/openapi.md b/aspnetcore/fundamentals/minimal-apis/openapi.md index ad62e5c5a5f1..4c13faff3570 100644 --- a/aspnetcore/fundamentals/minimal-apis/openapi.md +++ b/aspnetcore/fundamentals/minimal-apis/openapi.md @@ -4,7 +4,7 @@ author: rick-anderson description: Learn how to use OpenAPI (Swagger and Swashbuckle) features of minimal APIs in ASP.NET Core. ms.author: riande monikerRange: '>= aspnetcore-6.0' -ms.date: 10/11/2022 +ms.date: 10/24/2022 uid: fundamentals/minimal-apis/openapi --- @@ -210,7 +210,7 @@ If an endpoint can return different response types in different scenarios, you c :::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/minimal-apis/samples/MultipleResultTypes/Program.cs" id="snippet_multiple_result_types"::: - The `Results` union types declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata. + The `Results` *union types* declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata. The union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error. From f8110edd059fbd6006567cb0bc5242e88d45ff6d Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Mon, 24 Oct 2022 14:22:51 -0700 Subject: [PATCH 5/5] link to explanation of union type --- aspnetcore/fundamentals/minimal-apis/openapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/minimal-apis/openapi.md b/aspnetcore/fundamentals/minimal-apis/openapi.md index 4c13faff3570..9478a20b5780 100644 --- a/aspnetcore/fundamentals/minimal-apis/openapi.md +++ b/aspnetcore/fundamentals/minimal-apis/openapi.md @@ -210,7 +210,7 @@ If an endpoint can return different response types in different scenarios, you c :::code language="csharp" source="~/../AspNetCore.Docs.Samples/fundamentals/minimal-apis/samples/MultipleResultTypes/Program.cs" id="snippet_multiple_result_types"::: - The `Results` *union types* declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata. + The `Results` [union types](https://en.wikipedia.org/wiki/Union_type) declare that a route handler returns multiple `IResult`-implementing concrete types, and any of those types that implement `IEndpointMetadataProvider` will contribute to the endpoint’s metadata. The union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error.