Add OpenAPI binary file response documentation for ASP.NET Core 11.0 (#36754)

* Initial plan

* Add OpenAPI binary file response documentation for ASP.NET Core 11.0

- Added File() to TypedResults helper methods table
- Added "Describe binary file responses" section for Minimal APIs
- Added "Describe binary file responses" section for Controllers
- All new content uses moniker range >= aspnetcore-11.0
- Updated ms.date to 02/06/2026 and added ai-usage metadata

Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com>

* Enhance description for binary file responses

Clarify the usage of [ProducesResponseType<FileContentResult>] for binary file responses, specifying that it generates an OpenAPI description similar to the Minimal API example.

* Apply suggestions from code review

* Preserve .NET 10.0 version and update main file for .NET 11.0

- Created include-metadata10.md with original content for .NET 10.0
- Changed moniker range to "= aspnetcore-10.0" in include file
- Updated main file moniker range to ">= aspnetcore-11.0"
- Updated content moniker range to ">= aspnetcore-11.0"

Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com>

* Update include-metadata10.md

Set include for version 10.0 to be preserved as 10.0

* Apply suggestion from @wadepickett

Fixed article metadata monikerRange to start at 9.0

* Update include-metadata.md to remove version checks

Removed moniker directives for ASP.NET Core version 11.0 and updated binary file response descriptions.

* Update include-metadata.md

* Add OpenAPI metadata inclusion details

Added section on including OpenAPI metadata for endpoints.

* Update include-metadata10.md to remove old reference

Removed reference to include-metadata9.md.

* Add H2 heading to include-metadata9.md after moniker range

Added "## Include OpenAPI metadata for endpoints" heading after the moniker range line with blank lines before and after as requested.

Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: wadepickett <10985336+wadepickett@users.noreply.github.com>
Co-authored-by: Wade Pickett <wpickett@microsoft.com>

Author: Copilot

aspnetcore/fundamentals/openapi/include-metadata.md

@@ -1,20 +1,21 @@
 ---
 title: Include OpenAPI metadata in an ASP.NET Core app
+ai-usage: ai-assisted
 author: wadepickett
 description: Learn how to add OpenAPI metadata in an ASP.NET Core app.
-ms.author: wpickett
 monikerRange: '>= aspnetcore-9.0'
+ms.author: wpickett
 ms.custom: mvc
-ms.date: 06/12/2025
+ms.date: 02/06/2026
 uid: fundamentals/openapi/include-metadata
 ---
 # Include OpenAPI metadata in an ASP.NET Core app
 
 This article explains how to add OpenAPI metadata in an ASP.NET Core app.
 
-## Include OpenAPI metadata for endpoints
+:::moniker range=">= aspnetcore-11.0"
 
-:::moniker range=">= aspnetcore-10.0"
+## Include OpenAPI metadata for endpoints
 
 ASP.NET collects metadata from the web app's endpoints and uses it to generate an OpenAPI document.
 
@@ -360,11 +361,49 @@ Only return types that implement <xref:Microsoft.AspNetCore.Http.Metadata.IEndpo
 | NotFound()                   | 404         |
 | Conflict()                   | 409         |
 | UnprocessableEntity()        | 422         |
+| File()                       | 200         |
 
 All of these methods except `NoContent` have a generic overload that specifies the type of the response body.
 
 A class can be implemented to set the endpoint metadata and return it from the route handler.
 
+##### Describe binary file responses
+
+To describe endpoints that return binary file responses in the OpenAPI document, use the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method with `FileContentResult` as the type parameter to specify the response type and content type:
+
+```csharp
+app.MapPost("/filecontentresult", () =>
+{
+    var content = "This endpoint returns a FileContentResult!"u8.ToArray();
+    return TypedResults.File(content);
+})
+.Produces<FileContentResult>(contentType: MediaTypeNames.Application.Octet);
+```
+
+This generates an OpenAPI schema with `type: string` and `format: binary` for the `FileContentResult` type.
+
+The generated OpenAPI document describes the endpoint response as:
+
+```yaml
+responses:
+  '200':
+    description: OK
+    content:
+      application/octet-stream:
+        schema:
+          $ref: '#/components/schemas/FileContentResult'
+```
+
+With `FileContentResult` defined in `components/schemas` as:
+
+```yaml
+components:
+  schemas:
+    FileContentResult:
+      type: string
+      format: binary
+```
+
 ##### Set responses for `ProblemDetails`
 
 When setting the response type for endpoints that may return a ProblemDetails response, the following can be used to add the appropriate response metadata for the endpoint:
@@ -441,6 +480,22 @@ public async Task<ActionResult<Todo>> CreateOrReplaceTodo(string id, Todo todo)
 
 This example also illustrates how to define multiple response types for an action method, including the content type of the response body.
 
+##### Describe binary file responses
+
+To describe endpoints that return binary file responses, use the [`[ProducesResponseType<FileContentResult>]`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute) attribute to specify the response type and content type:
+
+```csharp
+[HttpPost("filecontentresult")]
+[ProducesResponseType<FileContentResult>(StatusCodes.Status200OK, MediaTypeNames.Application.Octet)]
+public IActionResult PostFileContentResult()
+{
+    var content = "This endpoint returns a FileContentResult!"u8.ToArray();
+    return new FileContentResult(content, MediaTypeNames.Application.Octet);
+}
+```
+
+This operation generates the same OpenAPI description as the [Minimal API binary file response example](xref:fundamentals/openapi/include-metadata#describe-binary-file-responses), with `FileContentResult` defined as `type: string` and `format: binary`.
+
 ---
 
 ### Exclude endpoints from the generated document
@@ -710,4 +765,5 @@ The following table shows the key differences beween the MVC JSON options and gl
 
 :::moniker-end
 
+[!INCLUDE[](~/fundamentals/openapi/includes/include-metadata10.md)]
 [!INCLUDE[](~/fundamentals/openapi/includes/include-metadata9.md)]