将 WebApi 方法的参数标记为已过时/已弃用 Swashbuckle / Swagger

Question

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

Deprecated Parameters

Use deprecated: true to mark a parameter as deprecated.

        - 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 可能是一个可以找到这种功能的地方，但它似乎没有。

Answer 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)
{
}

这样您就可以继续使用相同的方法，而不必强行更改所有客户端。但是，如果不仅仅是参数名称更改，例如类型，您将需要一个新方法

将 WebApi 方法的参数标记为已过时/已弃用 Swashbuckle / Swagger

Mark a WebApi method's parameter as obsolete / deprecated for Swashbuckle / Swagger

c#

swashbuckle

webapi

Deprecated Parameters

为什么？