將 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 你有這個結果