使用SWAGGER和ASP.NET CORE設(shè)置可選路由參數(shù)

使用SWAGGER和ASP.NET CORE設(shè)置可選路由參數(shù)

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

等等，什么是Swagger？

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

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

設(shè)置方案

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

人為設(shè)計(jì)的BlogSummaryController，其Get操作具有{day}的可選route參數(shù)

讓我們繼續(xù)運(yùn)行該站點(diǎn)，看看Swagger為我們創(chuàng)造了什么。

默認(rèn)Swagger生成

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

好了，那我該如何選擇路由參數(shù)？

我想有幾種方法可以解決這個(gè)問題。就是說，我發(fā)現(xiàn)的方法似乎效果很好，可以根據(jù)需要在全局和單獨(dú)應(yīng)用。

因此，事不宜遲，讓我們將其IOperationFilter作為起點(diǎn)。操作過濾器使我們可以對(duì)操作文檔進(jìn)行后期修改。這正是我們需要的，因?yàn)槲覀冃枰蜂N對(duì)可選路線參數(shù)的限制。

IOperationFilter使可選的路由參數(shù)在Swagger中實(shí)際上是可選的

在我的ReApplyOptionalRouteParameterOperationFilter課程中，我們首先測(cè)試該方法是否具有“ Route”屬性。如果是這樣，我們?nèi)缓髾z查URL中是否具有可選的route參數(shù)。如果不是這樣，我們就不會(huì)理會(huì)任何更改。另一方面，如果我們確實(shí)有一個(gè)，我將使用一些正則表達(dá)式來提取密鑰。現(xiàn)在我們有了鍵，我們?cè)诓僮魃险业搅艘粋€(gè)匹配參數(shù)，最后應(yīng)用了一些更改以使其成為可選鍵。！

應(yīng)用IOperationFilter

因此，現(xiàn)在我們有了一個(gè)，OperationFilter我們需要實(shí)際應(yīng)用它。您可以通過兩種方式進(jìn)行操作。第一種方法是在中全局應(yīng)用它SwaggerConfiguration。請(qǐng)注意，全局執(zhí)行此操作將需要Apply方法中的某些邏輯（以我的示例為例），以跳過不需要的地方應(yīng)用它。否則可能會(huì)給您帶來一些痛苦。

全局應(yīng)用OperationFilter

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

使用SwaggerOperationFilter在本地應(yīng)用OperationFilter

使用這兩種方法，我們現(xiàn)在可以看到Swagger不再需要該可選參數(shù)。世界是一個(gè)更好的地方。

帶有可選路線參數(shù)的新Swagger文檔

附加閱讀

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

我遇到的第二個(gè)實(shí)際上引用了第一個(gè)，并給了我解決方法的想法。存儲(chǔ)庫所有者（domaindrivendev）的評(píng)論重申，OpenAPI規(guī)范不允許這樣做。

所以你有它。我向您展示了一種強(qiáng)制其運(yùn)行的方法，即使規(guī)范完全表明這樣做并不可行。無論您的內(nèi)心渴望如何，您都可以利用這些知識(shí)來做。我選擇使用它。

結(jié)論

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