diff --git a/aspnetcore/release-notes/aspnetcore-11.md b/aspnetcore/release-notes/aspnetcore-11.md index 88c66575d831..dc476cdfd0cc 100644 --- a/aspnetcore/release-notes/aspnetcore-11.md +++ b/aspnetcore/release-notes/aspnetcore-11.md @@ -37,6 +37,8 @@ This section describes new features for Minimal APIs. This section describes new features for OpenAPI. +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-binary-file-response.md)] + ## Authentication and authorization This section describes new features for authentication and authorization. diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/openapi-binary-file-response.md b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-binary-file-response.md new file mode 100644 index 000000000000..c73a4fdb3aae --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-binary-file-response.md @@ -0,0 +1,57 @@ +### Describe binary file responses + +ASP.NET Core 11 introduces support for generating OpenAPI descriptions for operations that return binary file responses. This support maps the `FileContentResult` result type to an OpenAPI schema with `type: string` and `format: binary`. + +#### [Minimal APIs](#tab/minimal-apis) + +Use the `Produces` extension method with `T` of `FileContentResult` 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(contentType: MediaTypeNames.Application.Octet); +``` + +#### [Controllers](#tab/controllers) + +Use the `ProducesResponseType` attribute with `T` of `FileContentResult` to specify the response type and content type: + +```csharp +[HttpPost("filecontentresult")] +[ProducesResponseType(StatusCodes.Status200OK, MediaTypeNames.Application.Octet)] +public IActionResult PostFileContentResult() +{ + var content = "This endpoint returns a FileContentResult!"u8.ToArray(); + return new FileContentResult(content, MediaTypeNames.Application.Octet); +} +``` + +--- + +The generated OpenAPI document describes the endpoint response as: + +```yaml +responses: + '200': + description: OK + content: + application/octet-stream: + schema: + $ref: '#/components/schemas/FileContentResult' +``` + +The `FileContentResult` is defined in `components/schemas` as: + +```yaml +components: + schemas: + FileContentResult: + type: string + format: binary +```