【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载导读本指南基于 autoskills 技能库中的 aspnet-minimal-api-openapi SKILL.md 展开完整讲解如何用 ASP.NET Minimal API 编写结构清晰、类型正确、并且自带完整 OpenAPI/Swagger 文档的 HTTP 端点。你将掌握路由分组与端点过滤器、DTO 与验证、TypedResults/ResultsT1,T2类型体系以及基于 .NET 9 内置 OpenAPI 能力WithName、描述、文档/模式转换器的文档定制方案最终交付可直接复制运行的实战代码。为什么这份技能被收录进 autoskills在进入技术细节之前先看这份技能在 autoskills 项目中的定位便于理解它的适用范围。autoskills 通过扫描项目中的配置文件自动检测技术栈在 skills-map.ts 中aspnet-minimal-api的检测条件是在appsettings.json等配置文件中匹配到Microsoft.AspNetCore.OpenApi或Swashbuckle.AspNetCore依赖{ id: aspnet-minimal-api, name: ASP.NET Minimal API, detect: { configFiles: [appsettings.json], configFileContent: { scanDotNetLayout: true, patterns: [Microsoft.AspNetCore.OpenApi, Swashbuckle.AspNetCore], }, }, skills: [ github/awesome-copilot/aspnet-minimal-api-openapi, dotnet/skills/minimal-api-file-upload, ], }对应地lib.ts 中的resolveConfigFileContentPaths通过scanDotNetLayout递归扫描项目中的.sln、.csproj、.fsproj文件来确定候选路径而在 README.md 的检测矩阵中ASP.NET Minimal API 的识别信号同样是.csproj中的Microsoft.AspNetCore.OpenApi或Swashbuckle.AspNetCore。也就是说只要你的 .NET 项目引用了 OpenAPI 相关包autoskills 就会自动为你安装这份技能用于指导 AI 助手在编写端点时遵循本文所述的规范。技能的注册信息来源、commit、sha256 校验记录在 skills-registry/index.json 中。下面进入正题。一、API 组织让端点结构清晰可维护Minimal API 的一大优势是端点定义集中、样板代码少但随着端点数量增长散落的app.MapGet()会让代码难以维护。技能文档给出了四条组织原则1. 使用MapGroup()分组相关端点MapGroup()允许为一批端点共享统一的路由前缀和公共行为var app builder.Build(); var todos app.MapGroup(/api/todos) .RequireAuthorization() // 组级授权 .WithTags(Todos); // OpenAPI 标签分组 todos.MapGet(/, GetAllTodos); todos.MapGet(/{id}, GetTodoById); todos.MapPost(/, CreateTodo); todos.MapDelete(/{id}, DeleteTodo); app.Run();路由前缀、中间件、授权、标签等组级配置只需写一次组内所有端点自动继承避免在每个端点重复声明。2. 使用端点过滤器处理横切关注点当某些行为如日志、校验、限流、性能统计需要作用于多个端点时应使用IEndpointFilter而非在业务代码里重复实现。过滤器可以注册到单个端点也可以注册到整个路由组app.MapPost(/api/todos, CreateTodo) .AddEndpointFilterValidationFilterTodoRequest(); // 或者注册到组组内所有端点生效 var group app.MapGroup(/api/todos).AddEndpointFilterRequestLoggingFilter();过滤器位于中间件之后、端点处理器之前是面向端点层横切逻辑的标准挂载点。companion 技能 aspnet-core/references/apis-minimal-and-controllers.md 也强调use endpoint filters when cross-cutting behavior belongs at the endpoint layer即横切行为属于端点层时优先用端点过滤器。3. 大型 API 拆分为独立的端点类当单个文件无法容纳所有端点时可以把一组相关端点提取为独立类通过MapXxxApi()扩展方法组织public static class TodoEndpoints { public static RouteGroupBuilder MapTodoApi(this IEndpointRouteBuilder routes) { var group routes.MapGroup(/api/todos); group.MapGet(/, GetAll); group.MapGet(/{id}, GetById); group.MapPost(/, Create); return group; } } // Program.cs app.MapTodoApi();4. 复杂 API 采用基于功能feature的文件夹结构对于功能较多的 API可按功能而非技术类型组织目录使页面、端点、服务、验证、数据访问与测试易于追踪Features/ Todos/ Endpoints.cs // 端点定义 TodoRequest.cs // 请求 DTO TodoResponse.cs // 响应 DTO TodoService.cs // 业务逻辑 ValidationFilter.cs // 验证过滤器这与 aspnet-core 中keep feature slices cohesive保持功能切片内聚让页面、组件、端点、服务、数据访问和测试易于追踪的默认假设一致。二、请求与响应类型用显式 DTO 约束 API 契约技能文档强调显式定义请求与响应 DTO/模型这是 Minimal API 契约清晰度的核心。1. 定义明确的 DTO 与模型类不要直接把数据库实体暴露为 API 载荷而应定义独立的请求/响应模型让 API 契约与持久化模型解耦。companion 文档同样建议keep request and response DTOs separate from persistence models。2. 用 record 类型表达不可变对象对于请求/响应这类创建后不再修改的对象C# 的record是天然选择public record CreateTodoRequest( string Title, bool IsComplete false); public record TodoResponse( int Id, string Title, bool IsComplete, DateTimeOffset CreatedAt);record 自带值相等性与with表达式支持配合 init-only 属性可强化不可变性语义。3. 用验证属性强制约束在 DTO 属性上应用[Required]等验证特性让无效请求在到达业务逻辑之前就被拦截public record CreateTodoRequest { [Required, MinLength(1), MaxLength(200)] public string Title { get; init; } ; public bool IsComplete { get; init; } }在支持的框架版本上Minimal API 提供了内置验证支持.NET 10 中可用AddValidation()companion 文档建议优先使用内置验证而非另起一套并行验证基础设施。4. 用 ProblemDetails 与 StatusCodePages 获得标准错误响应不要为错误响应自造 JSON 结构应复用 ASP.NET Core 的标准机制ProblemDetailsService将错误编码为 RFC 7807 规范的application/problemjson响应含type、title、status、detail、instance字段StatusCodePages为未显式处理的 HTTP 状态码提供一致的错误页面/响应。companion 文档 apis-minimal-and-controllers.md 在共享实践一节同样强调UseProblemDetailsfor errors instead of ad hoc JSON shapes。builder.Services.AddProblemDetails(); builder.Services.AddStatusCodePages(); var app builder.Build(); app.UseStatusCodePages();三、类型处理让编译器替你保证响应契约这是本技能的核心技术主张用强类型让响应形状在编译期被固定下来。1. 强类型路由参数路由参数应声明为明确类型int、Guid、DateOnly等由模型绑定负责转换避免在处理器内手写解析与校验app.MapGet(/api/todos/{id:int}, (int id, TodoService svc) svc.FindById(id) is { } todo ? Results.Ok(todo) : Results.NotFound());{id:int}路由约束会拒绝非整数请求Guid、DateOnly等类型参数则由绑定器自动完成类型转换。2. 用ResultsT1, T2表达多种可能响应ResultsT1, T2允许在编译期声明端点可能返回的响应类型集合配合TypedResults工厂方法使 OpenAPI 文档能自动推断出完整的响应形态app.MapGet(/api/todos/{id}, GetTodoById) .WithName(GetTodoById); // 返回 200 或 404 ResultsOkTodoResponse, NotFound GetTodoById(int id, TodoService svc) svc.FindById(id) is { } todo ? TypedResults.Ok(new TodoResponse(todo.Id, todo.Title, todo.IsComplete, todo.CreatedAt)) : TypedResults.NotFound();3. 优先返回TypedResults而非ResultsTypedResults如TypedResults.Ok、TypedResults.NotFound、TypedResults.Created返回强类型的IResult实现让 OpenAPI 元数据推断更精确无类型化的Results.Ok会退化为运行时推断。companion 文档的Good defaults中也明确preferTypedResultsover untyped results。4. 善用 C# 10 语言特性可空性注解nullable annotations对引用类型标注?配合#nullable enable让可空性在编译期可见减少空引用缺陷init-only 属性对象初始化后不可再变强化 DTO 不可变语义顶层语句Program.cs使用顶层语句让最小 API 项目保持最小。资源创建场景还应遵循 companion 文档的建议使用TypedResults.Created/CreatedAtRoute模式返回 201 与Location头。四、OpenAPI 文档从能用到可发现、可消费技能文档的核心诉求是correct types and comprehensive OpenAPI/Swagger documentation——即让每个端点成为可发现、可消费的契约。1. 使用 .NET 9 内置的 OpenAPI 文档支持自 .NET 9 起Microsoft.AspNetCore.OpenApi包提供了内置的 OpenAPI 文档生成能力无需引入第三方 Swashbuckle 即可产出 OpenAPI 3.1 文档builder.Services.AddOpenApi(); var app builder.Build(); app.MapOpenApi(); // 暴露 /openapi/{documentName}.json这也解释了 autoskills 为何将Microsoft.AspNetCore.OpenApi作为检测 ASP.NET Minimal API 项目的信号——它是现代 .NET 项目内置 OpenAPI 能力的标准入口。2. 定义操作的 summary 与 description在端点处理器文档注释中编写摘要与详细说明使生成的文档对消费方前端、其他服务、AI 代理更友好/// summary返回指定 ID 的待办事项。/summary /// param nameid待办事项的唯一标识。/param /// returns200 与待办事项详情或 404。/returns app.MapGet(/api/todos/{id}, GetTodoById) .WithName(GetTodoById) .WithSummary(Returns a single todo by id) .WithDescription(Fetches the todo with the given id. Returns 404 when it does not exist.);3. 用WithName添加 operationIdWithName()为操作设置唯一标识OpenAPI 的operationId这对客户端代码生成如生成强类型 SDK至关重要app.MapGet(/api/todos/{id}, GetTodoById).WithName(GetTodoById);4. 用[Description()]描述属性与参数对 DTO 属性与参数添加[Description()]让 OpenAPI schema 携带字段语义说明using System.ComponentModel; public record CreateTodoRequest( [property: Description(Title of the todo item.)] string Title, [property: Description(Whether the todo is already completed.)] bool IsComplete false);5. 设置正确的请求/响应内容类型通过显式的Produces类型或TypedResults派生类型确保请求与响应的 Content-Type如application/json在文档中正确呈现。使用TypedResults时ResultsT1, T2的泛型参数会驱动 OpenAPI 推断响应 schema 与状态码。6. 用文档转换器Document Transformers添加 servers、tags、security schemes.NET 9的 OpenAPI 支持通过IDocumentTransformer在文档生成后做全局定制例如注入服务器地址、统一安全方案、标签分类builder.Services.AddOpenApi(options { options.AddDocumentTransformer((document, context, cancellationToken) { document.Servers new ListOpenApiServer { new() { Url https://api.example.com } }; document.SecuritySchemes[Bearer] new OpenApiSecurityScheme { Type SecuritySchemeType.Http, Scheme bearer, BearerFormat JWT }; return Task.CompletedTask; }); });典型用途包括部署环境不同的servers列表、tags归类、OAuth2/Bearer 等security schemes声明以及全局info元数据。7. 用模式转换器Schema Transformers定制 OpenAPI schemaISchemaTransformer允许对特定 schema 做细粒度定制例如为属性追加默认值、示例或扩展字段builder.Services.AddOpenApi(options { options.AddSchemaTransformer((schema, context, cancellationToken) { if (context.JsonTypeInfo.Type typeof(CreateTodoRequest)) { schema.Example new OpenApiObject { [title] new OpenApiString(Buy groceries), [isComplete] new OpenApiBoolean(false) }; } return Task.CompletedTask; }); });组合使用文档转换器与模式转换器可以在不改动业务代码的前提下让生成的 OpenAPI 文档达到对外发布标准。五、配套技能与延伸阅读aspnet-core更广泛的 ASP.NET Core 技能覆盖应用模型选择、管线、DI、安全、测试等其 apis-minimal-and-controllers.md 是 Minimal API 与控制器 API 选型的补充参考minimal-api-file-upload与本文技能同属aspnet-minimal-api技术组合当你的项目需要文件上传端点时可一并参考dotnet-best-practices 等 .NET 系列技能由dotnet技术检测项统一触发与本文技能协同指导整个 .NET 项目的编码质量。总结编写高质量的 ASP.NET Minimal API 端点本质上是在四个层面持续做对结构上用MapGroup、端点过滤器和功能文件夹组织代码契约上用显式 DTO、record 与验证属性约束请求/响应形状类型上用强类型参数与TypedResults/ResultsT1,T2让响应在编译期固定文档上用 .NET 9 内置 OpenAPI 支持配合WithName、描述与文档/模式转换器把端点变成机器可读、可发现、可消费的契约。把这套规范落到你的 .NET 项目中AI 助手、前端团队与外部消费者都能基于同一份准确契约高效协作。赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐BT 下载总卡在 99%trackerslist 公共 Tracker 清单 5 分钟接入指南BT 下载总卡在 99%trackerslist 公共 Tracker 清单 5 分钟接入指南 下载卡在 99%做种数却长期是 0多半不是带宽问题。给 BASP.NET Core OpenAPI集成自动生成API文档的完整指南ASP.NET Core OpenAPI集成自动生成API文档的完整指南 ASP.NET Core OpenAPI集成是现代Web开发中的必备技能它能自动为后端Web框架openapi-fetch 完整指南为 OpenAPI 3 规范构建 6 kB 的类型安全 Fetch 客户端openapi fetch 完整指南为 OpenAPI 3 规范构建 6 kB 的类型安全 Fetch 客户端 openapi fetch 是 openapi开发工具代码生成后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考