用途:为 .NET 10 应用提供内置 OpenAPI 文档生成方案,替代 Swashbuckle。核心原则是使用框架自带的 Microsoft.AspNetCore.OpenApi,Swashbuckle 已从 .NET 9 模板移除且不再推荐。
主要能力:用 TypedResults.Ok<T>() 自动生成正确的响应架构,Results.Ok() 不会;通过文档、操作、架构三类转换器定制安全方案、全局响应与架构;用 .WithName()、.WithSummary()、.WithTags() 为每个端点添加元数据,供规范与客户端生成器使用;支持多文档、XML 注释、构建期生成规范与 YAML 端点。
使用方式:注册 builder.Services.AddOpenApi(),在开发环境调用 app.MapOpenApi(),默认服务于 /openapi/v1.json。安全方案通过 AddDocumentTransformer<BearerSecuritySchemeTransformer>() 添加。多文档用多次 AddOpenApi("v1") 并配合 WithGroupName()。XML 注释需在项目文件设置 <GenerateDocumentationFile>true</GenerateDocumentationFile>,且仅对命名方法生效,lambda 上的注释不会被编译器捕获。构建期生成需引用 Microsoft.Extensions.ApiDescription.Server 并设置 OpenApiDocumentsDirectory。YAML 端点用 app.MapOpenApi("/openapi/{documentName}.yaml")。
适用场景:新建 .NET 10 API 项目、需要安全方案与响应文档、多版本 API、客户端代码生成(Kiota 或 NSwag)、构建期产出规范文件。
限制与注意:.NET 10 中不要使用 WithOpenApi()(已弃用,产生 ASPDEPR002 警告),改用 AddOpenApiOperationTransformer();不要使用非类型化 Results;不要省略 WithName,否则客户端生成的方法名质量差;不要使用 OpenApiAny,改用 System.Text.Json.Nodes 的 JsonNode;OpenAPI 版本默认 3.1,消费方需要时可强制 3.0。文档 UI 推荐 Scalar。具体收费、平台与效果资料暂未提供。