已弃用的 API 应在 Swagger UI 中进行相应标记

Question

功能要求

如今，可以使用 Swagger 对 API 进行版本控制，并且周围的大多数事情都可以完美地工作。我在这里真正缺少的是让任何 Swagger UI 用户都清楚 API版本已被标记为已弃用的可能性。

此处描述了 aspnetcore 中的 API 弃用。我的期望是在 API 组名称旁边有一个图标或标签，上面写着“OBSOLETE”或“DEPRECATED”。

附注：

Swashbuckle Swagger ASPNET.Core github 项目问题跟踪器建议在 SO 上打开功能请求。

编辑：

使用 ApiVersion 属性将整个控制器标记为已弃用。如果将控制器标记为 [已过时]，则所有方法均呈灰色且文本带有删除线。但这不是我想要的。我不想将我的代码库标记为[已过时]。我想将特定的 API 版本标记为已弃用，以便人们知道他们应该切换到较新的版本。

   [ApiVersion("1", Deprecated = true)]
   [Route("v{version:apiVersion}/[controller]")]
   [Authorize("my.auth.policy")]
   [ApiController]
   public class MyApiController
   {
      // do stuff
   }

我当前的解决方法是这样的：在我的 Startup 中，我添加 swaggerUI 并在 swagger 端点下拉显示上执行自定义格式设置。

app.UseSwagger();
            app.UseSwaggerUI(options =>
            {
                foreach (ApiVersionDescription apiVersionDescription in apiVersionDescriptionProvider.ApiVersionDescriptions.OrderByDescending(a => a.ApiVersion))
                {
                    string isDeprecated = apiVersionDescription.IsDeprecated ? " (DEPRECATED)" : string.Empty;
                    options.SwaggerEndpoint($"{Configuration["PathBase"]}/swagger/{apiVersionDescription.GroupName}/swagger.json",
                        $"{apiVersionDescription.GroupName.ToUpperInvariant()}{isDeprecated}");
                }
            });

Answer 1

@海伦

定义

public class CustomHeaderFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
            operation.Parameters = new List<OpenApiParameter>();

        var apiDescription = context.ApiDescription;
        if (apiDescription.IsDeprecated())
        {
            operation.Deprecated = true;
        }
    }
}

使用

builder.Services.AddSwaggerGen(g =>
{
    g.OperationFilter<CustomHeaderFilter>();
}).AddSwaggerGenNewtonsoftSupport();

接口必须有以下内容

[ApiVersion("1.0", Deprecated = true)]
public class WeatherForecastController : ControllerBase

结果