示例工程【免费下载链接】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 仓库中的projects/net9/open-api-4示例讲解如何在不依赖 NSwag 文档生成能力的前提下仅借用 NSwag 的 Swagger UI 中间件来可视化 ASP.NET Core 内置 OpenAPI 生成器产出的 OpenAPI 文档。读完本文你将掌握AddOpenApi/MapOpenApi与AddOpenApiDocument/UseSwaggerUi的搭配用法、DocumentPath重定向背后的机制以及如何通过ExcludeFromDescription控制文档内容。背景为什么需要NSwag 只做 UI、内置生成器只管产出在 ASP.NET Core 引入内置 OpenAPI 支持之前生成 OpenAPI 文档通常依赖第三方包如 NSwag、Swashbuckle。正如仓库 projects/net9/README.md 所记载从 .NET 9 开始框架自带 OpenAPI 文档生成能力Microsoft.AspNetCore.OpenApi包不再必须依赖第三方生成器。但框架内置生成器只负责产出OpenAPI 文档JSON/YAML并不自带成熟的交互式可视化界面。于是出现了一种常见的工程组合内置生成器负责按端点元数据自动生成规范文档NSwag 的 Swagger UI负责提供浏览器端交互界面发送请求、查看 Schema 等。open-api-4示例正是这种组合的最小可运行示范它用 NSwag 的 UI 去可视化内置生成器的产物这正是 projects/net9/README.md 中对该示例的描述 Use NSWag to visualize built-in OpenAPI generator。示例项目结构open-api-4位于仓库的 projects/net9/open-api-4 目录共 4 个文件文件作用Program.cs全部应用逻辑服务注册、中间件管线、端点定义open-api-4.csproj项目文件声明框架与第三方包依赖open-api-4.slnVisual Studio 解决方案文件README.md示例说明需要说明的是该示例虽然位于net9目录下但其项目文件实际以net10.0为目标框架这与仓库中多个示例后续迁移目标框架的做法一致因此运行前请确保本机安装了与之匹配的 .NET SDK。依赖配置两行 PackageReferenceopen-api-4.csproj 的完整内容如下Project SdkMicrosoft.NET.Sdk.Web PropertyGroup TargetFrameworknet10.0/TargetFramework ImplicitUsingstrue/ImplicitUsings /PropertyGroup ItemGroup PackageReference IncludeMicrosoft.AspNetCore.OpenApi Version10.0.11 / PackageReference IncludeNSwag.AspNetCore Version14.7.1 / /ItemGroup /Project两个包各司其职Microsoft.AspNetCore.OpenApi10.0.11内置 OpenAPI 生成器所在的包提供AddOpenApi()与MapOpenApi()NSwag.AspNetCore14.7.1提供 NSwag 的 Swagger UI 中间件即AddOpenApiDocument()与UseSwaggerUi()。ImplicitUsings启用后常见的命名空间如Microsoft.AspNetCore.Builder无需显式using这也是 Program.cs 中看不到using语句的原因。核心代码逐段解析Program.cs 总共 37 行完整代码为var builder WebApplication.CreateBuilder(); builder.Services.AddOpenApi(); builder.Services.AddOpenApiDocument(); var app builder.Build(); app.MapOpenApi(); app.UseSwaggerUi(options { options.DocumentPath /openapi/{documentName}.json; }); app.MapGet(/, () { var html html body h1OpenAPI JSON document/h1 ul li You can check the generated OpenAPI document a href/openapi/v1.jsonhere/a. /li li You can check the Swagger UI a href/swagger/index.htmlhere/a. /li /body /html ; return TypedResults.Content(html, text/html); }).ExcludeFromDescription(); //This is not an API endpoint app.MapGet(/hello/{name}, (string name) $Hello {name}!); app.Run();下面按职责拆解。1.AddOpenApi()注册内置 OpenAPI 生成器builder.Services.AddOpenApi();将框架内置的 OpenAPI 文档生成服务注册进依赖注入容器。它会在应用启动时扫描已映射的端点基于路由、参数、返回类型等元数据自动构建 OpenAPI 3.1 文档。2.AddOpenApiDocument()注册 NSwag 的文档相关服务builder.Services.AddOpenApiDocument();是 NSwag.AspNetCore 提供的服务注册入口。从源码结构可以推断它用于满足UseSwaggerUi()中间件对文档服务的依赖需求NSwag 的 Swagger UI 中间件默认需要一个文档提供者才能工作。关键点本示例真正想让 UI 展示的并不是 NSwag 自己生成的文档而是内置生成器的产物。实现这一点靠的是下一步的DocumentPath配置NSwag 自身的文档生成在这里只是配角——这正是示例标题中 visualize the built-in OpenAPI generator 的含义。3.MapOpenApi()映射内置文档端点app.MapOpenApi();注册内置 OpenAPI 文档的 HTTP 端点。未指定路径时默认路径为/openapi/{documentName}.json默认文档名为v1因此实际访问地址是/openapi/v1.json—— 内置生成器产出的 OpenAPI JSON 文档这个默认路径与下一步DocumentPath中配置的路径完全一致是两者能衔接起来的关键。4.UseSwaggerUi()DocumentPath让 NSwag UI 消费内置文档app.UseSwaggerUi(options { options.DocumentPath /openapi/{documentName}.json; });这是整个示例的核心机制。NSwag 的 Swagger UI 中间件默认从自己生成的文档地址取数据而这里通过options.DocumentPath将取数地址显式指向内置生成器的端点模板/openapi/{documentName}.jsonUI 页面本身由 NSwag 提供默认挂在/swagger/index.html页面加载时按DocumentPath拉取文档实际拿到的是内置生成器产出的 JSON结果就是NSwag 的壳内置生成器的芯。5. 首页端点与ExcludeFromDescription()app.MapGet(/, () { ... 返回 HTML ... }) .ExcludeFromDescription(); //This is not an API endpoint/返回一个简单的 HTML 首页方便在浏览器中快速跳转查看生成的 OpenAPI 文档/openapi/v1.json查看 Swagger UI/swagger/index.html。由于这个首页只是一个导航页、并非真正的业务 API代码通过.ExcludeFromDescription()将它排除出 OpenAPI 文档。这一点与仓库中 projects/net9/open-api-3/Program.cs 的做法一致该示例的 README 也专门提到用ExcludeFromDescription排除MapGet(/)。如果去掉这行生成的文档里就会混入一个返回text/html的伪端点。6. 真正的 API 端点app.MapGet(/hello/{name}, (string name) $Hello {name}!);/hello/{name}是示例中唯一正式的 API 端点带路由参数name返回字符串。它会在 OpenAPI 文档中被完整描述路径、参数、响应类型你可以在 Swagger UI 中直接对它发起请求验证。运行与验证在示例目录下执行dotnet run开发调试时也可使用dotnet watch run与仓库中其他示例的运行方式一致。应用启动后按顺序验证打开/看到导航首页确认存在两个链接打开/openapi/v1.json确认能拿到由内置生成器产出的 OpenAPI JSON 文档打开/swagger/index.html确认 NSwag 的 Swagger UI 正常渲染且 UI 中展示的正是步骤 2 的文档内容。如果一切正常你会在 Swagger UI 的路径列表中看到/hello/{name}而不会看到/因为它已被ExcludeFromDescription排除。仓库内的延伸对照同一主题的多种组合open-api-4并非孤立示例仓库中还有一批同主题示例可对照阅读帮你理解生成器与 UI 解耦的设计projects/net9/open-api-3只使用内置生成器AddOpenApiMapOpenApi不引入任何 UI 中间件是open-api-4的裸版前置projects/net10/open-api-9同样用UseSwaggerUi但通过MapOpenApi同时映射 JSON 与 YAML 两个端点并把DocumentPath指向/openapi/{documentName}.yaml展示如何让 NSwag UI 消费 YAML 格式文档projects/net10/open-api-8 与 projects/minimal-api/open-api-1改用 Scalar 作为 UIMapScalarApiReference并演示 XML 文档注释summary、remarks、param如何填充进 OpenAPI 描述projects/net11/open-api-12 与 projects/net11/open-api-13展示 OpenAPI 3.2 的新能力如 SSEtext/event-stream的itemSchema描述。对照阅读可以看出内置生成器负责出文档UI 组件负责给人看两者通过文档端点路径解耦可以自由组合——这正是本示例想要传达的工程模式。小结open-api-4用极简代码演示了一个实用组合AddOpenApi()MapOpenApi()让框架内置生成器产出 OpenAPI 文档AddOpenApiDocument()UseSwaggerUi()引入 NSwag 的交互界面而DocumentPath一行的配置让 UI 直接消费内置文档。配合ExcludeFromDescription过滤非 API 端点即可在不引入完整第三方生成器的情况下获得开箱即用的 API 文档体验。若需将文档以 YAML 格式输出或换用 Scalar 界面仓库中 projects/net10/open-api-9 与 projects/net10/open-api-8 提供了可直接对照的完整实现。赞分享示例工程【免费下载链接】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 生成 OpenAPI YAML 文档内置 YAML 序列化端点与 NSwag Swagger UI 实战ASP.NET Core 10 生成 OpenAPI YAML 文档内置 YAML 序列化端点与 NSwag Swagger UI 实战 本文基于 pract示例工程radix-vue MenubarSeparatorMenubar 分隔线组件的 API、实现与实战用法radix vue MenubarSeparatorMenubar 分隔线组件的 API、实现与实战用法 在 radix vue 的 Menubar菜单栏示例工程ASP.NET Core 9 实战内置 OpenAPI 文档生成器与 TypedResults.InternalServerError 状态码practical-aspnetcore 示例解读ASP.NET Core 9 实战内置 OpenAPI 文档生成器与 TypedResults.InternalServerError 状态码practic示例工程上一篇实时响应Apache Arrow重构机器人控制系统数据处理的终极指南下一篇Ravi 静态类型实战教程从入门到精通的 5 个核心案例创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考