用途：为 ASP.NET Core 项目生成 OpenAPI 文档，并指导从 Swashbuckle 迁移、使用 NSwag 生成客户端。
主要能力：Microsoft.AspNetCore.OpenApi 是 .NET 9+ 第一方推荐方案，新项目模板默认包含；.NET 10 支持 OpenAPI 3.1 与 JSON Schema draft 2020-12。支持多文档（按版本或功能分组）、文档转换器（IOpenApiDocumentTransformer）、操作转换器（IOpenApiOperationTransformer）、架构转换器（AddSchemaTransformer），以及 WithName、WithSummary、WithDescription、WithTags、Produces、ProducesProblem 等端点元数据增强。
使用方式：注册 builder.Services.AddOpenApi()，在开发环境调用 app.MapOpenApi() 提供 /openapi/v1.json；多文档用 AddOpenApi("v1", ...) 与 AddOpenApi("v2", ...)。转换器通过 options.AddDocumentTransformer、AddOperationTransformer、AddSchemaTransformer 注册。MapOpenApi() 只提供原始 JSON，需另加 Scalar、独立 Swagger UI 等界面。
迁移与替代：Swashbuckle 已不再积极维护且不支持 OpenAPI 3.1，现有项目应规划迁移；IDocumentFilter、IOperationFilter、ISchemaFilter 分别对应文档、操作、架构转换器。NSwag 可用于文档生成、C#/TypeScript 客户端生成与 UI，CLI 安装命令为 dotnet tool install --global NSwag.ConsoleCore。
限制与注意：Microsoft.AspNetCore.OpenApi 包版本须与项目目标框架主版本一致，勿混用 Swashbuckle 与内置 OpenAPI，勿对新 .NET 9+ 项目推荐 Swashbuckle；Swashbuckle 并非正式弃用，只是不再积极维护。最小 API 端点模式、API 版本策略、认证授权不在本技能范围内。
前置条件：.NET 9.0+（内置包），.NET 10.0 支持 OpenAPI 3.1 与 Scalar 集成；NSwag.AspNetCore 可选。