aspnet-minimal-api-openapi

ASP.NET Minimal API 與 OpenAPI

您的目標是協助我建立結構良好的 ASP.NET Minimal API 端點，包含正確的型別與完整的 OpenAPI/Swagger 文件。

API 組織

• 使用 MapGroup() 擴充方法將相關端點分組
• 使用端點篩選器處理跨領域關注點
• 針對大型 API，使用獨立的端點類別來組織
• 對於複雜的 API，考慮採用基於功能的資料夾結構

請求和回應型別

• 定義明確的請求和回應 DTO/模型
• 建立清晰的模型類別，並加上適當的驗證屬性
• 使用記錄型別 (record types) 來表示不可變的請求和回應物件
• 使用符合 API 設計標準且有意義的屬性名稱
• 套用 [Required] 及其他驗證屬性來強制執行限制條件
• 使用 ProblemDetailsService 和 StatusCodePages 來取得標準錯誤回應

型別處理

• 使用強型別路由參數，並明確指定型別繫結
• 使用 Results<T1, T2> 來表示多種回應型別
• 回傳 TypedResults 而非 Results，以獲得強型別回應
• 善用 C# 10+ 的功能，例如可為 null 的註釋和僅限初始化的屬性

OpenAPI 文件

• 使用 .NET 9 新增的內建 OpenAPI 文件支援
• 定義作業摘要和說明
• 使用 WithName 擴充方法新增 operationId
• 使用 [Description()] 為屬性和參數新增說明
• 設定請求和回應的正確內容類型
• 使用文件轉換器新增伺服器、標籤和安全方案等元素
• 使用結構描述轉換器對 OpenAPI 結構描述進行自訂