示例工程【免费下载链接】practical-aspnetcorePractical samples of ASP.NET Core 11, 10, 9, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.项目地址https://gitcode.com/gh_mirrors/pr/practical-aspnetcore点击查看免费下载导读本文围绕 practical-aspnetcore 仓库中的 open-api-14 示例讲解 ASP.NET Core 11.NET 11中一个易被忽略但对 API 文档质量影响重大的改进文件类响应结果FileContentResult、FileContentHttpResult、FileStreamResult、FileStreamHttpResult现在会正确映射为 OpenAPI 文档中的type: string, format: binary描述。读完本文你将掌握如何在 Minimal API 中返回二进制文件、如何通过ProducesT()声明文件响应以及如何在生成的/openapi/v1.json文档中验证这一描述是否符合 OpenAPI 规范。背景文件响应在 OpenAPI 文档中的描述难题为什么需要format: binary在 OpenAPI 规范中二进制内容的标准表达方式是type: string, format: binary。这是客户端代码生成器如 OpenAPI Generator识别该字段/响应是文件字节流的关键标记——没有format: binary生成器会把响应误判为普通字符串type: string导致下载、流式处理等二进制语义全部丢失。在 .NET 11 之前ASP.NET Core 内置 OpenAPI 文档生成器对文件类型结果的描述并不理想需要在代码中手动补齐Produces元数据或编写自定义文档处理器才能让生成的文档正确表达二进制响应。这也是本仓库 TODO.md 中把该改进列为强候选微示例Tier 2 strong candidate的原因。ASP.NET Core 11 的新行为从源码结构看ASP.NET Core 11 将四类文件结果统一纳入 OpenAPI 文档生成器的类型映射逻辑结果类型所属框架说明FileContentResultMVCMicrosoft.AspNetCore.Mvc以字节数组为内容的文件结果FileContentHttpResultMinimal APIMicrosoft.AspNetCore.Http.HttpResults与 MVC 版对应的 Minimal API 实现FileStreamResultMVC以流为内容的文件结果FileStreamHttpResultMinimal API与 MVC 版对应的 Minimal API 实现这四类结果现在都会映射为 OpenAPI 文档中的type: string, format: binary并且这种映射是在ProducesT()/ProducesResponseTypeT()声明的基础上完成的见 TODO.md 的说明。示例全景open-api-14 项目结构该示例位于 projects/net11/open-api-14是一个结构极简的微示例遵循仓库 AGENTS.md 中所有应用代码放在Program.cs、一个示例只聚焦一个概念的约定projects/net11/open-api-14/ ├── Program.cs ├── README.md └── open-api-14.csproj项目文件 open-api-14.csproj 内容如下Project SdkMicrosoft.NET.Sdk.Web PropertyGroup TargetFrameworknet11.0/TargetFramework ImplicitUsingstrue/ImplicitUsings LangVersionpreview/LangVersion /PropertyGroup ItemGroup PackageReference IncludeMicrosoft.AspNetCore.OpenApi Version11.0.0-preview.7.26381.103 / /ItemGroup /ProjectTargetFramework为net11.0属于 ASP.NET Core 11.NET 112025 年 11 月 GA时代的功能演示通过 NuGet 包Microsoft.AspNetCore.OpenApi版本11.0.0-preview.7.26381.103引入内置 OpenAPI 支持LangVersion为preview这与 .NET 11 的预览版 SDK 环境一致global.json 将 SDK 固定为11.0.100-rc.1.26425.128rollForward: major。核心代码逐行解析Program.cs 完整代码如下using System.Net.Mime; using Microsoft.AspNetCore.Http.HttpResults; var builder WebApplication.CreateBuilder(args); builder.Services.AddOpenApi(); var app builder.Build(); app.MapOpenApi(); app.MapGet(/, () Results.Text( htmlbody h1Binary file responses in OpenAPI/h1 ul lia href/openapi/v1.jsonOpenAPI document/a/li lia href/fileGET /file/a download a PDF-ish blob/li /ul /body/html , text/html)).ExcludeFromDescription(); app.MapGet(/file, () TypedResults.File(PDF-1.4 sample binary payloadu8.ToArray())) .ProducesFileContentHttpResult(contentType: MediaTypeNames.Application.Octet); app.Run();第 1 步启用内置 OpenAPIbuilder.Services.AddOpenApi();这一行注册了 .NET 内置的 OpenAPI 文档生成服务来自Microsoft.AspNetCore.OpenApi无需任何第三方包Swashbuckle / NSwag 都不是必需的。从 .NET 9 引入、.NET 10 完善、.NET 11 持续演进的这一内置能力在本仓库其他示例中反复出现例如 open-api-1 和 open-api-3。第 2 步暴露文档端点app.MapOpenApi();MapOpenApi()注册文档端点默认地址为/openapi/v1.json返回 JSON 格式的 OpenAPI 文档。在 .NET 11 中默认文档版本为 OpenAPI 3.2参见同目录系列示例 open-api-13 与 open-api-12后者展示了options.OpenApiVersion OpenApiSpecVersion.OpenApi3_2的显式设置方式。第 3 步定义二进制文件端点app.MapGet(/file, () TypedResults.File(PDF-1.4 sample binary payloadu8.ToArray())) .ProducesFileContentHttpResult(contentType: MediaTypeNames.Application.Octet);这是整个示例的核心拆解如下TypedResults.File(...)返回一个FileContentHttpResult。参数是ReadOnlyMemorybyte通过...u8.ToArray()把 UTF-8 字符串字面量转成字节数组。这里故意使用一段PDF-1.4 sample binary payload字节串模拟 PDF 文件内容避免在仓库中存放真实二进制文件.ProducesFileContentHttpResult(contentType: MediaTypeNames.Application.Octet)显式声明该端点会以application/octet-stream内容类型返回一个FileContentHttpResult。MediaTypeNames.Application.Octet即标准二进制 MIME 类型application/octet-stream结合 ASP.NET Core 11 的新映射逻辑文档生成器会把这个响应描述为type: string, format: binary。第 4 步首页排除在文档之外app.MapGet(/, () Results.Text(..., text/html)).ExcludeFromDescription();首页用Results.Text返回一段 HTML方便浏览器访问并通过.ExcludeFromDescription()明确将其排除出 OpenAPI 文档。这与本仓库其他 OpenAPI 示例的惯例一致如 open-api-8 中对首页同样调用ExcludeFromDescription()并注释 This is not an API endpoint。生成的 OpenAPI 文档形态在运行该示例后访问首页提供的两个链接即可验证GET /openapi/v1.json——查看生成的 OpenAPI 文档GET /file——实际下载这段PDF 风格的二进制 blob。其中/file端点在文档中的响应描述从源码结构看应呈现为如下形态{ paths: { /file: { get: { responses: { 200: { description: OK, content: { application/octet-stream: { schema: { type: string, format: binary } } } } } } } } }关键点在于schema节点type: string加上format: binary。这一组合正是 OpenAPI 规范中表示任意二进制字节流的标准写法是客户端代码生成器正确生成下载文件代码的前提。从 MVC 到 Minimal API四种结果类型的统一该改进并不只针对 Minimal API。原文档明确指出四类结果类型全部受益MVC 侧FileContentResult与FileStreamResult。MVC 控制器返回文件流的经典写法可参考仓库中的 result-filestream 示例其中Hegel()动作通过FileStreamResult(System.IO.File.OpenRead(path), application/pdf)返回 PDF 流并设置FileDownloadName提供下载文件名Minimal API 侧FileContentHttpResult与FileStreamHttpResult。本示例的TypedResults.File(...)属于前者如果改为从FileStream或PathString构造则对应后者。无论走哪一条路径.NET 11 的文档生成器都会统一产出type: string, format: binary消除了两套 API 风格在文档描述上的不一致。使用前提与验证方式SDK 前提该示例依赖 .NET 11 预览/RC 及以上 SDK。projects/net11/README.md 明确指出这些示例需要 SDK 11 RC1且 global.json 将 SDK 固定为11.0.100-rc.1.26425.128rollForward: major运行方式在示例目录内执行dotnet run本仓库约定使用dotnet watch run进行开发调试参见 TODO.md 中的验证约定然后访问http://localhost:5000/验证要点打开/openapi/v1.json定位/file路径确认responses.200.content[application/octet-stream].schema为{type: string, format: binary}配套联动open-api-14 与同目录系列示例共同构成 .NET 11 OpenAPI 能力矩阵——open-api-15 演示同一状态码下多个ProducesT()生成独立 content 条目open-api-13 演示 OpenAPI 3.2 默认版本与 SSE 的itemSchema描述open-api-12 演示 HTTP Query 方法支持。结合阅读可以完整把握 .NET 11 在 OpenAPI 文档生成上的演进脉络。小结ASP.NET Core 11 让二进制文件响应在 OpenAPI 文档中的描述回归规范无论你使用 Minimal API 的TypedResults.File还是 MVC 的FileStreamResult生成的文档都会正确标注type: string, format: binary。这一改进让下载文件类 API 的文档、代码生成与客户端消费链路更加可靠。open-api-14 示例以十余行代码完整演示了从声明ProducesFileContentHttpResult到验证/openapi/v1.json的闭环可作为你在 .NET 11 项目中处理文件响应文档化的直接参考。赞分享示例工程【免费下载链接】practical-aspnetcorePractical samples of ASP.NET Core 11, 10, 9, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.项目地址https://gitcode.com/gh_mirrors/pr/practical-aspnetcore点击查看免费下载相关推荐在 ASP.NET Core 10 Minimal API 中用 XML 文档注释填充 OpenAPI 响应描述open-api-10 实战在 ASP.NET Core 10 Minimal API 中用 XML 文档注释填充 OpenAPI 响应描述open api 10 实战 导读 本文基于示例工程practical-aspnetcore 实战在 ASP.NET Core 11 中启用 OpenAPI 3.2 并描述 HTTP QUERY 方法practical aspnetcore 实战在 ASP.NET Core 11 中启用 OpenAPI 3.2 并描述 HTTP QUERY 方法 导读 本示例工程NSwag缓存控制API响应缓存的OpenAPI描述与实现NSwag缓存控制API响应缓存的OpenAPI描述与实现 在API开发中缓存控制是提升性能和减少服务器负载的关键技术。然而如何在OpenAPI规范中准确开发工具代码生成API设计上一篇gbrain 的 brain-taxonomist 技能基于活动 Schema Pack 的动态智能归档门Filing Gate下一篇awesome-claude-skills 实战用 YouTube Video Downloader 技能实现可控画质与格式的视频下载创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考