将 WebApi 方法的参数标记为过时/不推荐用于 Swashbuckle / Swagger

Posted 2023-03-31

【中文标题】将 WebApi 方法的参数标记为过时/不推荐用于 Swashbuckle / Swagger

【英文标题】：Mark a WebApi method's parameter as obsolete / deprecated for Swashbuckle / Swagger

【发布时间】：2020-02-14 09:50:49

【问题描述】：

根据我对Swagger Specification 的理解，可以将参数标记为过时：

不推荐使用的参数

使用deprecated: true 将参数标记为已弃用。

        - in: query
          name: format
          required: true
          schema:
            type: string
            enum: [json, xml, yaml]
          deprecated: true
          description: Deprecated, use the appropriate `Accept` header instead.```

如何让 Swashbuckle 为参数生成此参数？

为什么？

我有一个类似于以下的控制器方法：

[HttpGet]
public async Task<IActionResult> Execute(bool? someName)

我想更改查询字符串参数名称，同时暂时保持向后兼容，所以 我想做类似的事情：

[HttpGet]
public async Task<IActionResult> Execute([Obsolete("Use someNewName instead.")] bool? someName, bool? someNewName)

    someNewName = someNewName ?? someName;

但是，Obsolete 不能应用于参数。我预计Swashbuckle.AspNetCore.Annotations 可能是一个可以找到这种功能的地方，但它似乎没有。

【问题讨论】：

您是否尝试将方法标记为过时，而不是参数？

【参考方案1】：

您不会将参数标记为过时，如果参数过时，则整个方法都会过时。您需要声明一个带有新方法签名的新方法，并将旧方法标记为过时。像这样

[HttpGet]
[Obsolete("Use Execute with bool? someNewName instead.")]
public async Task<IActionResult> Execute(bool? someName)



[HttpGet]
public async Task<IActionResult> Execute(bool? someNewName)

如果您只更改了参数的名称，则可以改为使用 Bind 属性将 URI 元素绑定到不同名称的变量，如下所示：

[HttpGet]
public async Task<IActionResult> Execute([Bind(Prefix = "someNewName")] bool? someName)

这将允许您继续使用相同的方法，而不必强制更改所有客户端。但是，如果不仅仅是参数的名称发生了变化，例如类型，您将需要一个新方法