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

[Copilot]

• Review the target file include-metadata.md to understand current structure
• Add File() method to the TypedResults table (lines 350-362)
• Add "Describe binary file responses" subsection in Minimal APIs section (after line 366)
• Add "Describe binary file responses" subsection in Controllers section (after line 443)
• Ensure all new content uses moniker range >= aspnetcore-11.0
• Update metadata (ms.date) according to repository conventions
• Verify changes align with Microsoft Writing Style Guide
• Review and validate all changes
• Create include-metadata10.md to preserve .NET 10.0 version
• Update main file to use moniker range >= aspnetcore-11.0
• Add H2 heading to include-metadata9.md

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[11.0 P1] Include OpenAPI metadata: Update for describing binary file responses</issue_title>
<issue_description>Related to #36747

Description

Draft suggestions below:

Feature changes to represent:

• Using Produces<FileContentResult> with contentType: MediaTypeNames.Application.Octet for Minimal APIs
• Using [ProducesResponseType<FileContentResult>] attribute for Controllers
• The FileContentResult maps to type: string and format: binary in the OpenAPI schema

---

Recommended Documentation Updates

Except for updates in older moniker ranges < 11.0 where we are simply providing a note and pointing to the newer topic, all new entries should be in a new moniker range of:
:::moniker range=">= aspnetcore-11.0"

1. aspnetcore/fundamentals/openapi/include-metadata.md (Minimal APIs Section)

File: aspnetcore/fundamentals/openapi/include-metadata.md

Location: After line 366 (after the "A class can be implemented..." sentence), right before the ##### Set responses for ProblemDetails heading at line 368. This way the general-purpose content stays grouped together.

Add the following subsection:

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:

```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:

responses:
  '200':
    description: OK
    content:
      application/octet-stream:
        schema:
          $ref: '#/components/schemas/FileContentResult'

With FileContentResult defined in components/schemas as:

components:
  schemas:
    FileContentResult:
      type: string
      format: binary

---

2. aspnetcore/fundamentals/openapi/include-metadata.md (Controllers Section)

**File:** `aspnetcore/fundamentals/openapi/include-metadata.md`

**Location:** After line 443 (after "This example also illustrates how to define multiple response types...") and before the --- that closes the tabs. This keeps the binary file response section as a natural extension at the end of the Controllers tab content.

**Add the following subsection:**

```markdown
 Describe binary file responses

To describe endpoints that return binary file responses, use the [`[ProducesResponseType<FileContentResult>]`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute) attribute:

```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 generates an OpenAPI schema with type: string and format: binary for the FileContentResult type.

---

 3. aspnetcore/fundamentals/openapi/include-metadata.md (TypedResults Table)

**File:** `aspnetcore/fundamentals/openapi/include-metadata.md`

**Location:** Lines 350-362 (the TypedResults helper method table)

**Update the table to include `File()`:**

```markdown
| `TypedResults` helper method | Status code |
| ---------------------------- | ----------- |
| Ok()                         | 200         |
| Created()                    | 201         |
| CreatedAtRoute()             | 201         |
| Accepted()                   | 202         |
| AcceptedAtRoute()            | 202         |
| NoContent()                  | 204         |
| BadRequest()                 | 400         |
| ValidationProblem()          | 400         |
| NotFound()                   | 404         |
| Conflict()                   | 409         |
| UnprocessableEntity()        | 422         |
| File()                       | 200         |

---

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/include-metadata?view=aspnetcore-10.0&tabs=minimal-apis

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/include-metadata.md

Document ID

cbc730ec-642f-480d-4a41-044c6c6ef7d3

Platform Id

4bbf4c77-ca40-25d5-0673-fab1102c2291

Article author

@wadepickett

Metadata

• ID: cbc730ec-642f-480d-4a41-044c6c6ef7d3
• PlatformId: 4bbf4c77-ca40-25d5-0673-fab1102c2291
• Service: aspnet-core
• Sub-service: fundamentals

[Related Issues](https://github.com/dotne...

• Fixes [11.0 P1] Include OpenAPI metadata: Update for describing binary file responses #36748

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/openapi/include-metadata.md	aspnetcore/fundamentals/openapi/include-metadata

[wadepickett]

@copilot,
This file preserves versioning of the article for each version of .NET with each file include representing a version.
The .NET 10.0 version needs to be preserved.
The following original file:
https://[raw.githubusercontent.com/dotnet/AspNetCore.Docs/refs/heads/main/aspnetcore/fundamentals/openapi/include-metadata.md]

1. Needs its contents moved to a new path and file name of:
   aspnetcore/fundamentals/openapi/includes/include-metadata10.md
2. the new include-metadata10.md needs its moniker ranged changed to: :::moniker range="= aspnetcore-10.0"

Also the updated file in this PR:
aspnetcore/fundamentals/openapi/include-metadata.md

1. Needs to have a single moniker range of :::moniker range=">= aspnetcore-11.0" for its entire contents.

[Copilot]

@copilot,
This file preserves versioning of the article for each version of .NET with each file include representing a version.
The .NET 10.0 version needs to be preserved.
...

Completed in commit 085bf15.

Created aspnetcore/fundamentals/openapi/includes/include-metadata10.md with the original file content and moniker range set to = aspnetcore-10.0.

Updated aspnetcore/fundamentals/openapi/include-metadata.md with moniker range >= aspnetcore-11.0 for the entire file (both frontmatter and content).

[wadepickett]

@copilot,
this file:
aspnetcore/fundamentals/openapi/includes/include-metadata9.md

after the first line which is a monker range, needs to start with this H2 and have a blank like before and after the H2:

Include OpenAPI metadata for endpoints

[Copilot]

@copilot,
this file:
aspnetcore/fundamentals/openapi/includes/include-metadata9.md
...

Completed in commit 74b2022. Added the H2 heading "## Include OpenAPI metadata for endpoints" after the moniker range line with blank lines before and after.

[wadepickett]

@tdykstra,

The new content is essentially the two sections at the bottom, located here:
https://github.com/dotnet/AspNetCore.Docs/pull/36754/changes#diff-030b33a82c3e80363193a57c724ee7e2558cd24be935904d6e3f955d4cf3734bR370

The rest is just moving the old version 10 into its own include to make way for v11.