使用SWAGGER和ASP.NET CORE設置可選路由參數

根據OpenAPI 3.0，這是不可能的。但是，如果您真的希望成為現實呢？您是否必須解決并允許您的Swagger文檔出錯？我在這里向您展示如何使用Swagger和ASP.NET Core設置可選的路由參數。

等等，什么是Swagger？

在偶然的情況下，您導航到了這篇文章，卻不知道Swagger是什么，我如何快速介紹一下？“ Swagger是描述REST API的格式的一組規則，因此，它可用于在產品經理，測試人員和開發人員之間共享文檔……” – Swagger入門。

Swagger的一種常見用法是通過Swagger UI提供一個界面。Swagger UI允許您可視化API的資源并與之交互。它比Postman或類似工具更具針對性。

設置方案

現在我們有了一個基本的想法，Swagger是什么，我將建立一個人為的方案。讓我們假設我們有一個提供博客摘要的API。該API可以根據許多條件返回摘要，所有條件均從URL提供。在此特定用例中，我正在運行Swashbuckle.AspNetCore v5.3.3。此版本使用OpenApi v3.x。據我了解，2.x中的工作原理有所不同。您可以在MSDN或GitHub上的Swashbuckle上閱讀。

人為設計的BlogSummaryController，其Get操作具有{day}的可選route參數

讓我們繼續運行該站點，看看Swagger為我們創造了什么。

默認Swagger生成

您會注意到，即使我定義{day?}了可選的路由選擇器，Swagger仍在告訴我們它是必需的。

好了，那我該如何選擇路由參數？

我想有幾種方法可以解決這個問題。就是說，我發現的方法似乎效果很好，可以根據需要在全局和單獨應用。

因此，事不宜遲，讓我們將其IOperationFilter作為起點。操作過濾器使我們可以對操作文檔進行后期修改。這正是我們需要的，因為我們需要撤銷對可選路線參數的限制。

IOperationFilter使可選的路由參數在Swagger中實際上是可選的

在我的ReApplyOptionalRouteParameterOperationFilter課程中，我們首先測試該方法是否具有“ Route”屬性。如果是這樣，我們然后檢查URL中是否具有可選的route參數。如果不是這樣，我們就不會理會任何更改。另一方面，如果我們確實有一個，我將使用一些正則表達式來提取密鑰。現在我們有了鍵，我們在操作上找到了一個匹配參數，最后應用了一些更改以使其成為可選鍵。！

應用IOperationFilter

因此，現在我們有了一個，OperationFilter我們需要實際應用它。您可以通過兩種方式進行操作。第一種方法是在中全局應用它SwaggerConfiguration。請注意，全局執行此操作將需要Apply方法中的某些邏輯（以我的示例為例），以跳過不需要的地方應用它。否則可能會給您帶來一些痛苦。

全局應用OperationFilter

另一種方法是對OperationFilter要修改的每個動作單獨應用。為了在本地應用它，您只需使用SwaggerOperationFilterattribute并指定類型。請注意，您需要Swashbuckle.AspNetCore.Annotations對該屬性使用nuget包。如果您全局應用它，那么您也不應在本地應用它。

使用SwaggerOperationFilter在本地應用OperationFilter

使用這兩種方法，我們現在可以看到Swagger不再需要該可選參數。世界是一個更好的地方。

帶有可選路線參數的新Swagger文檔

附加閱讀

早些時候，我提到了OpenAPI 3不支持可選路由參數的內容。在谷歌搜索如何解決此問題時，我在Swashbuckle GitHub上遇到了幾個“問題”。在第一個有一個參考的意見深，其指向一個OpenAPI的specifiation文件。其要點是必須*必填路徑中的變量。

我遇到的第二個實際上引用了第一個，并給了我解決方法的想法。存儲庫所有者（domaindrivendev）的評論重申，OpenAPI規范不允許這樣做。

所以你有它。我向您展示了一種強制其運行的方法，即使規范完全表明這樣做并不可行。無論您的內心渴望如何，您都可以利用這些知識來做。我選擇使用它。

結論

Swagger（和Swagger UI）是記錄和可視化API的整潔方法。Swashbuckle.AspNetCore是使用.NET Core生成該文檔的好方法。即使ASP.NET Core允許使用可選的路由參數，OpenAPI規范也會在您的路徑中禁止使用可選的值。我向您展示了一種解決方法，使您的文檔與實現相匹配。我們使用來完成IOperationFilter。該示例中的所有代碼都可以在GitHub上找到。

總結

以上是生活随笔為你收集整理的使用SWAGGER和ASP.NET CORE设置可选路由参数的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。