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

Question

根据我对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 为参数生成这个？

为什么？

我有一个 controller 方法，如下所示：

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

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

Answer 2

可以通过 OperationFilter 到 go

在 programe.cs 集中

options.OperationFilter<OpenApiParameterObsoleteFilter>();

在 OpenApiParameterObsoleteFilter 集中创建 OpenApiParameterObsoleteFilter.cs 文件

 public class OpenApiParameterIgnoreFilter : Swashbuckle.AspNetCore.SwaggerGen.IOperationFilter
{
    public void Apply(Microsoft.OpenApi.Models.OpenApiOperation operation, Swashbuckle.AspNetCore.SwaggerGen.OperationFilterContext context)
    {
        if (operation == null || context == null || context.ApiDescription?.ParameterDescriptions == null)
            return;

        var parametersToHide = context.ApiDescription.ParameterDescriptions
            .Where(parameterDescription => ParameterHasIgnoreAttribute(parameterDescription))
            .ToList();


        var parametersToObsolete = context.ApiDescription.ParameterDescriptions
                .Where(parameterDescription => ParameterHasDepreciate(parameterDescription))
                .ToList();
        foreach (var parameterToObsolete in parametersToObsolete)
        {
            var parameter = operation.Parameters.FirstOrDefault(parameter => string.Equals(parameter.Name, parameterToObsolete.Name, System.StringComparison.Ordinal));
            parameter.Deprecated = true;
        }

    }
    private static bool ParameterHasDepreciate(Microsoft.AspNetCore.Mvc.ApiExplorer.ApiParameterDescription parameterDescription)
    {
        if (parameterDescription.ModelMetadata is Microsoft.AspNetCore.Mvc.ModelBinding.Metadata.DefaultModelMetadata metadata)
        {
            return
                (metadata.Attributes.Attributes?.Any(attribute => attribute.GetType() == typeof(ObsoleteAttribute)) ?? false);
        }

        return false;
    }
}

在您的参数上添加过时属性（在我的例子中是 object）

    [Obsolete]
    public long? ID_CONDUCT { get => iD_CONDUCT; set => iD_CONDUCT = value; }

在 swagger 你有这个结果