Merge pull request #33270 from dotnet/main

Merge to Live

.github/CODEOWNERS

@@ -2,6 +2,8 @@
 # Each line is a file pattern followed by one or more owners.
 
 # More details are here: https://help.github.com/articles/about-codeowners/
+# Initial experience with this file was not all positive, so most lines are currently commented out.
+# It will be easy to give it another trial should we decide to do that.
 
 # The '*' pattern is global owners.
 
@@ -16,22 +18,22 @@
 # /aspnetcore/client-side/ 
 # /aspnetcore/common/ 
 # /aspnetcore/data/ 
-/aspnetcore/diagnostics/ @Rick-Anderson
-/aspnetcore/fundamentals/ @tdykstra
+# /aspnetcore/diagnostics/ @Rick-Anderson
+# /aspnetcore/fundamentals/ @tdykstra
 # /aspnetcore/getting-started/ 
-/aspnetcore/grpc/ @wadepickett
-/aspnetcore/host-and-deploy/ @Rick-Anderson
+# /aspnetcore/grpc/ @wadepickett
+# /aspnetcore/host-and-deploy/ @Rick-Anderson
 # /aspnetcore/includes/ 
-/aspnetcore/log-mon/ @Rick-Anderson
-/aspnetcore/migration/ @Rick-Anderson
+# /aspnetcore/log-mon/ @Rick-Anderson
+# /aspnetcore/migration/ @Rick-Anderson
 # /aspnetcore/mobile/ 
 # /aspnetcore/mvc/ 
-# /aspnetcore/performance/ 
+/aspnetcore/performance/caching/ @tdykstra 
 # /aspnetcore/razor-pages/ 
 # /aspnetcore/release-notes/ 
-/aspnetcore/security/ @Rick-Anderson
-/aspnetcore/signalr/ @wadepickett
+# /aspnetcore/security/ @Rick-Anderson
+# /aspnetcore/signalr/ @wadepickett
 # /aspnetcore/test/ 
-/aspnetcore/tutorials/ @wadepickett
-/aspnetcore/web-api/ @wadepickett @Rick-Anderson
-/aspnetcore/whats-new/ @Rick-Anderson
+# /aspnetcore/tutorials/ @wadepickett
+# /aspnetcore/web-api/ @wadepickett @Rick-Anderson
+# /aspnetcore/whats-new/ @Rick-Anderson

.openpublishing.redirection.json

@@ -25,6 +25,11 @@
             "redirect_url": "/aspnet/core/fundamentals/aot/request-delegate-generator/rdg_ids",
             "redirect_document_id": false
         },
+        {
+            "source_path": "aspnetcore/fundamentals/minimal-apis/openapi.md",
+            "redirect_url": "/aspnet/core/fundamentals/openapi/aspnetcore-openapi",
+            "redirect_document_id": false
+        },
         {
             "source_path": "aspnetcore/fundamentals/minimal-apis/handle-errrors.md",
             "redirect_url": "/aspnet/core/fundamentals/minimal-apis/handle-errors",

aspnetcore/fundamentals/minimal-apis.md

@@ -254,7 +254,7 @@ The following code disables `ValidateScopes` and `ValidateOnBuild` in `Developme
 ## See also
 
 * <xref:fundamentals/minimal-apis>
-* <xref:fundamentals/minimal-apis/openapi>
+* <xref:fundamentals/openapi/aspnetcore-openapi>
 * <xref:fundamentals/minimal-apis/responses>
 * <xref:fundamentals/minimal-apis/min-api-filters>
 * <xref:fundamentals/minimal-apis/handle-errors>

aspnetcore/fundamentals/minimal-apis/includes/minimal-apis6.md

@@ -329,7 +329,7 @@ The preceding code displays `The link to the hello endpoint is /hello` from the
 Endpoint names:
 
 * Must be globally unique.
-* Are used as the OpenAPI operation id when OpenAPI support is enabled. For more information, see [OpenAPI](xref:fundamentals/minimal-apis/openapi).
+* Are used as the OpenAPI operation id when OpenAPI support is enabled. For more information, see [OpenAPI](xref:fundamentals/openapi/aspnetcore-openapi).
 
 ### Route Parameters
 
@@ -753,6 +753,6 @@ For more information, see <xref:security/cors?view=aspnetcore-6.0>
 
 ## See also
 
-[OpenAPI support in minimal APIs](xref:fundamentals/minimal-apis/openapi)
+[OpenAPI support in minimal APIs](xref:fundamentals/openapi/aspnetcore-openapi)
 
 :::moniker-end

aspnetcore/fundamentals/minimal-apis/includes/minimal-apis7.md

@@ -221,7 +221,7 @@ Moved to uid: tutorials/min-web-api
 
 ## See also
 
-* <xref:fundamentals/minimal-apis/openapi>
+* <xref:fundamentals/openapi/aspnetcore-openapi>
 * <xref:fundamentals/minimal-apis/responses>
 * <xref:fundamentals/minimal-apis/min-api-filters>
 * <xref:fundamentals/minimal-apis/handle-errors>

aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8.md

@@ -196,7 +196,7 @@ Authenticated file upload requests are supported using an [Authorization header]
 
 #### Binding to forms with IFormCollection, IFormFile, and IFormFileCollection
 
-Binding from form-based parameters using <xref:Microsoft.AspNetCore.Http.IFormCollection>, <xref:Microsoft.AspNetCore.Http.IFormFile>, and <xref:Microsoft.AspNetCore.Http.IFormFileCollection> is supported. [OpenAPI](xref:fundamentals/minimal-apis/openapi) metadata is inferred for form parameters to support integration with [Swagger UI](xref:tutorials/web-api-help-pages-using-swagger).
+Binding from form-based parameters using <xref:Microsoft.AspNetCore.Http.IFormCollection>, <xref:Microsoft.AspNetCore.Http.IFormFile>, and <xref:Microsoft.AspNetCore.Http.IFormFileCollection> is supported. [OpenAPI](xref:fundamentals/openapi/aspnetcore-openapi) metadata is inferred for form parameters to support integration with [Swagger UI](xref:tutorials/web-api-help-pages-using-swagger).
 
 The following code uploads files using inferred binding from the `IFormFile` type:
 

aspnetcore/fundamentals/minimal-apis/includes/responses7-8.md

@@ -63,7 +63,7 @@ The <xref:Microsoft.AspNetCore.Http.Results> and <xref:Microsoft.AspNetCore.Http
 Returning `TypedResults` rather than `Results` has the following advantages:
 
 * `TypedResults` helpers return strongly typed objects, which can improve code readability, unit testing, and reduce the chance of runtime errors.
-* The implementation type [automatically provides the response type metadata for OpenAPI](/aspnet/core/fundamentals/minimal-apis/openapi#describe-response-types) to describe the endpoint.
+* The implementation type [automatically provides the response type metadata for OpenAPI](/aspnet/core/fundamentals/openapi/aspnetcore-openapi#describe-response-types) to describe the endpoint.
 
 Consider the following endpoint, for which a `200 OK` status code with the expected JSON response is produced.
 
@@ -73,7 +73,7 @@ In order to document this endpoint correctly the extensions method `Produces` is
 
 :::code language="csharp" source="~/tutorials/min-web-api/samples/7.x/todo/Program.cs" id="snippet_112b":::
 
-For more information about describing a response type, see [OpenAPI support in minimal APIs](/aspnet/core/fundamentals/minimal-apis/openapi#describe-response-types-1).
+For more information about describing a response type, see [OpenAPI support in minimal APIs](/aspnet/core/fundamentals/openapi/aspnetcore-openapi#describe-response-types-1).
 
 As mentioned previously, when using `TypedResults`, a conversion is not needed. Consider the following minimal API which returns a `TypedResults` class
 

aspnetcore/fundamentals/minimal-apis/includes/route-handlers.md

@@ -43,7 +43,7 @@ The preceding code displays `The link to the hello route is /hello` from the `/`
 Endpoint names:
 
 * Must be globally unique.
-* Are used as the OpenAPI operation id when OpenAPI support is enabled. For more information, see [OpenAPI](xref:fundamentals/minimal-apis/openapi).
+* Are used as the OpenAPI operation id when OpenAPI support is enabled. For more information, see [OpenAPI](xref:fundamentals/openapi/aspnetcore-openapi).
 
 ### Route Parameters
 

aspnetcore/fundamentals/minimal-apis/responses.md

@@ -67,7 +67,7 @@ The <xref:Microsoft.AspNetCore.Http.Results> and <xref:Microsoft.AspNetCore.Http
 Returning `TypedResults` rather than `Results` has the following advantages:
 
 * `TypedResults` helpers return strongly typed objects, which can improve code readability, unit testing, and reduce the chance of runtime errors.
-* The implementation type [automatically provides the response type metadata for OpenAPI](/aspnet/core/fundamentals/minimal-apis/openapi#describe-response-types) to describe the endpoint.
+* The implementation type [automatically provides the response type metadata for OpenAPI](/aspnet/core/fundamentals/openapi/aspnetcore-openapi#describe-response-types) to describe the endpoint.
 
 Consider the following endpoint, for which a `200 OK` status code with the expected JSON response is produced.
 
@@ -77,7 +77,7 @@ In order to document this endpoint correctly the extensions method `Produces` is
 
 :::code language="csharp" source="~/tutorials/min-web-api/samples/7.x/todo/Program.cs" id="snippet_112b":::
 
-For more information about describing a response type, see [OpenAPI support in minimal APIs](/aspnet/core/fundamentals/minimal-apis/openapi#describe-response-types-1).
+For more information about describing a response type, see [OpenAPI support in minimal APIs](/aspnet/core/fundamentals/openapi/aspnetcore-openapi#describe-response-types-1).
 
 As mentioned previously, when using `TypedResults`, a conversion is not needed. Consider the following minimal API which returns a `TypedResults` class
 

aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

@@ -1,14 +1,16 @@
 ---
-title: Get started with Microsoft.AspNetCore.OpenApi
+title: Work with OpenAPI documents
 author: captainsafia
 description: Learn how to generate and customize OpenAPI documents in an ASP.NET Core app
 ms.author: safia
-monikerRange: '>= aspnetcore-9.0'
+monikerRange: '>= aspnetcore-6.0'
 ms.custom: mvc
 ms.date: 5/22/2024
 uid: fundamentals/openapi/aspnetcore-openapi
 ---
-# Get started with Microsoft.AspNetCore.OpenApi
+# Work with OpenAPI documents
+
+:::moniker range=">= aspnetcore-9.0"
 
 The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) package provides built-in support for OpenAPI document generation in ASP.NET Core. The package provides the following features:
 
@@ -544,3 +546,7 @@ The output shows any issues with the OpenAPI document.
 
 ✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)
 ```
+
+::: moniker-end
+
+[!INCLUDE[](~/fundamentals/openapi/includes/aspnetcore-openapi6-8.md)]

aspnetcore/fundamentals/minimal-apis/includes/openapi8.md → aspnetcore/fundamentals/openapi/includes/aspnetcore-openapi6-8.md

@@ -1,12 +1,6 @@
-:::moniker range="> aspnetcore-6.0 < aspnetcore-9.0"
+:::moniker range="> aspnetcore-6.0 <= aspnetcore-8.0"
 
-The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) is a programming language-agnostic standard for documenting HTTP APIs. This standard is supported in minimal APIs through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:
-
-* Generating information about the endpoints in the app.
-* Gathering the information into a format that matches the OpenAPI schema.
-* Exposing the generated OpenAPI schema via a visual UI or a serialized file.
-
-Minimal APIs provide built-in support for generating information about endpoints in an app via the `Microsoft.AspNetCore.OpenApi` package. Exposing the generated OpenAPI definition via a visual UI requires a third-party package. 
+Minimal APIs provide built-in support for generating information about endpoints in an app via the `Microsoft.AspNetCore.OpenApi` package. Exposing the generated OpenAPI definition via a visual UI requires a third-party package. For information about support for OpenAPI in controller-based APIs, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true).
 
 The following code is generated by the ASP.NET Core minimal web API template and uses OpenAPI:
 
@@ -207,3 +201,37 @@ Minimal APIs support API versioning via the [Asp.Versioning.Http package](https:
 * <xref:fundamentals/minimal-apis/security>
 
 :::moniker-end
+
+:::moniker range="= aspnetcore-6.0"
+
+A minimal API app can describe the [OpenAPI specification](https://swagger.io/specification/) for route handlers using [Swashbuckle](https://www.nuget.org/packages/Swashbuckle.AspNetCore/).
+
+For information about support for OpenAPI in controller-based APIs, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true).
+
+The following code is a typical ASP.NET Core app with OpenAPI support:
+
+[!code-csharp[](~/fundamentals/minimal-apis/samples/WebMinAPIs/Program.cs?name=snippet_swag)]
+
+## Exclude OpenAPI description
+
+In the following sample, the `/skipme` endpoint is excluded from generating an OpenAPI description:
+
+[!code-csharp[](~/fundamentals/minimal-apis/samples/WebMinAPIs/Program.cs?name=snippet_swag2)]
+
+## Describe response types
+
+The following example uses the built-in result types to customize the response:
+
+[!code-csharp[](~/fundamentals/minimal-apis/samples/todo/Program.cs?name=snippet_getCustom)]
+
+## Add operation ids to OpenAPI
+
+[!code-csharp[](~/fundamentals/minimal-apis/samples/todo/Program.cs?name=snippet_name)]
+
+## Add tags to the OpenAPI description
+
+The following code uses an [OpenAPI grouping tag](https://swagger.io/docs/specification/grouping-operations-with-tags/):
+
+[!code-csharp[](~/fundamentals/minimal-apis/samples/todo/Program.cs?name=snippet_grp)]
+
+:::moniker-end

aspnetcore/fundamentals/openapi/includes/overview6-8.md

@@ -0,0 +1,13 @@
+:::moniker range=">= aspnetcore-6.0 <= aspnetcore-8.0"
+
+The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) is a programming language-agnostic standard for documenting HTTP APIs. This standard is supported in minimal APIs through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:
+
+* Generating information about the endpoints in the app.
+* Gathering the information into a format that matches the OpenAPI schema.
+* Exposing the generated OpenAPI schema via a visual UI or a serialized file.
+
+Minimal APIs provide built-in support for generating information about endpoints in an app via the `Microsoft.AspNetCore.OpenApi` package. Exposing the generated OpenAPI definition via a visual UI requires a third-party package.
+
+For information about support for OpenAPI in controller-based APIs, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true). 
+
+:::moniker-end

aspnetcore/fundamentals/openapi/overview.md

@@ -1,15 +1,19 @@
 ---
-title: How to use OpenAPI in ASP.NET Core API apps
+title: Overview of OpenAPI support in ASP.NET Core API apps
 author: rick-anderson
-description: Learn how to use OpenAPI features in ASP.NET Core.
+description: Learn about OpenAPI features in ASP.NET Core.
 ms.author: wpickett
-monikerRange: '>= aspnetcore-9.0'
+monikerRange: '>= aspnetcore-6.0'
 ms.date: 8/02/2024
 uid: fundamentals/openapi/overview
 ---
 
 # OpenAPI support in ASP.NET Core API apps
 
+[!INCLUDE[](~/includes/not-latest-version.md)]
+
+:::moniker range=">= aspnetcore-9.0"
+
 ASP.NET Core supports the generation of OpenAPI documents in controller-based and minimal APIs apps.
 The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) is a programming language-agnostic standard for documenting HTTP APIs. This standard is supported in ASP.NET Core apps through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:
 
@@ -65,3 +69,7 @@ the output directory by setting the `OpenApiDocumentsDirectory` property.
 ## Additional Resources
 
 * <xref:fundamentals/minimal-apis/security>
+
+:::moniker-end
+
+[!INCLUDE[](~/fundamentals/openapi/includes/overview6-8.md)]

aspnetcore/fundamentals/portable-object-localization.md

@@ -172,6 +172,14 @@ For the Czech culture, the three translations are different. The French and Engl
 
 ## Advanced tasks
 
+### Using additional arguments
+
+The argument at index zero `{0}` always represents the count value. When invoking the `Plural` method it is possible to add additional arguments and their index will then start at one (`1`).
+
+```cshtml
+<p>@Localizer.Plural(count, "There is one item with the color {1}.", "There are {0} items. The main color is {1}.", color)</p>
+```
+
 ### Contextualizing strings
 
 Applications often contain the strings to be translated in several places. The same string may have a different translation in certain locations within an app (Razor views or class files). A PO file supports the notion of a file context, which can be used to categorize the string being represented. Using a file context, a string can be translated differently, depending on the file context (or lack of a file context).

aspnetcore/mvc/views/working-with-forms/sample/final/ViewModels/CountryViewModel.cs

@@ -11,7 +11,7 @@ public class CountryViewModel
         {
             new SelectListItem { Value = "MX", Text = "Mexico" },
             new SelectListItem { Value = "CA", Text = "Canada" },
-            new SelectListItem { Value = "US", Text = "USA"  },
+            new SelectListItem { Value = "US", Text = "USA" },
         };
     }
-}
+}

aspnetcore/release-notes/aspnetcore-7.0.md

@@ -173,7 +173,7 @@ The [`WithOpenApi`](https://github.com/dotnet/aspnetcore/blob/8a4b4deb09c04134f2
 
 Minimal APIs now support annotating operations with descriptions and summaries for OpenAPI spec generation. You can call extension methods <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.WithDescription%2A> and <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.WithSummary%2A> or use attributes [[EndpointDescription]](xref:Microsoft.AspNetCore.Http.EndpointDescriptionAttribute) and [[EndpointSummary]](xref:Microsoft.AspNetCore.Http.EndpointSummaryAttribute)).
 
-For more information, see [OpenAPI in minimal API apps](xref:fundamentals/minimal-apis/openapi?view=aspnetcore-7.0)
+For more information, see [OpenAPI in minimal API apps](xref:fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-7.0)
 
 ### File uploads using IFormFile and IFormFileCollection
 

aspnetcore/release-notes/aspnetcore-8.0.md

@@ -528,7 +528,7 @@ Starting in ASP.NET Core 8.0, the [RequestLocalizationOptions.CultureInfoUseUser
 
 Explicit binding to form values using the [[FromForm]](xref:Microsoft.AspNetCore.Mvc.FromFormAttribute) attribute is now supported. Parameters bound to the request with `[FromForm]` include an [anti-forgery token](xref:security/anti-request-forgery). The anti-forgery token is validated when the request is processed.
 
-Inferred binding to forms using the <xref:Microsoft.AspNetCore.Http.IFormCollection>, <xref:Microsoft.AspNetCore.Http.IFormFile>, and <xref:Microsoft.AspNetCore.Http.IFormFileCollection> types is also supported. [OpenAPI](xref:fundamentals/minimal-apis/openapi) metadata is inferred for form parameters to support integration with [Swagger UI](xref:tutorials/web-api-help-pages-using-swagger).
+Inferred binding to forms using the <xref:Microsoft.AspNetCore.Http.IFormCollection>, <xref:Microsoft.AspNetCore.Http.IFormFile>, and <xref:Microsoft.AspNetCore.Http.IFormFileCollection> types is also supported. [OpenAPI](xref:fundamentals/openapi/aspnetcore-openapi) metadata is inferred for form parameters to support integration with [Swagger UI](xref:tutorials/web-api-help-pages-using-swagger).
 
 For more information, see:
 

aspnetcore/toc.yml

@@ -844,7 +844,7 @@ items:
         items:
           - name: Overview
             uid: fundamentals/openapi/overview
-          - name: Get started with Microsoft.AspNetCore.OpenApi
+          - name: Work with OpenAPI documents
             uid: fundamentals/openapi/aspnetcore-openapi
           - name: OpenAPI tools
             uid: fundamentals/openapi/openapi-tools