使用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上找到。