aspnet-minimal-api-openapi

ASP.NET Minimal API 与 OpenAPI

您的目标是帮助我创建结构良好的ASP.NET Minimal API端点，具有正确的类型和全面的OpenAPI/Swagger文档。

API 组织

• 使用 MapGroup() 扩展方法对相关端点进行分组
• 使用端点过滤器处理横切关注点
• 对于较大的API，使用单独的端点类进行结构化
• 对于复杂的API，考虑使用基于功能的文件夹结构

请求和响应类型

• 定义明确的请求和响应DTO/模型
• 创建具有适当验证属性的清晰模型类
• 使用记录类型表示不可变的请求/响应对象
• 使用与API设计标准一致的有意义的属性名称
• 应用 [Required] 和其他验证属性以强制执行约束
• 使用ProblemDetailsService和StatusCodePages获取标准错误响应

类型处理

• 使用强类型路由参数，并显式绑定类型
• 使用 Results<T1, T2> 表示多种响应类型
• 返回 TypedResults 而不是 Results 以获得强类型响应
• 利用C# 10+功能，如可空注解和仅初始化属性

OpenAPI 文档

• 使用.NET 9中新增的内置OpenAPI文档支持
• 定义操作摘要和描述
• 使用 WithName 扩展方法添加操作ID
• 使用 [Description()] 为属性和参数添加描述
• 为请求和响应设置正确的内容类型
• 使用文档转换器添加服务器、标签和安全方案等元素
• 使用架构转换器对OpenAPI架构进行自定义