C# .NET5 Web API如何在Swagger(Swashbuckle)中隐藏接口可选参数

核心思路 #

通过自定义参数特性 + Swagger OperationFilter 实现精准隐藏指定接口的单个参数，不影响其他参数、接口的正常展示，也不会干扰参数的实际接收逻辑。

实现步骤 #

• 第一步：自定义用于标记要隐藏参数的特性

[AttributeUsage(AttributeTargets.Parameter)]
public class SwaggerIgnoreParameterAttribute : Attribute
{
}

• 第二步：实现Swagger OperationFilter，扫描并移除标记了特性的参数

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;

public class SwaggerIgnoreParameterFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var ignoredParams = context.MethodInfo.GetParameters()
            .Where(param => param.GetCustomAttribute<SwaggerIgnoreParameterAttribute>() != null)
            .Select(param => param.Name)
            .ToList();

        if (!ignoredParams.Any()) return;

        foreach (var paramName in ignoredParams)
        {
            var target = operation.Parameters.FirstOrDefault(p => 
                p.Name.Equals(paramName, StringComparison.OrdinalIgnoreCase));
            if (target != null) operation.Parameters.Remove(target);
        }
    }
}

• 第三步：在Swagger配置中注册该Filter
  打开Startup.cs文件，在ConfigureServices方法的AddSwaggerGen配置块中添加Filter注册：

services.AddSwaggerGen(options =>
{
    // 保留你原有的Swagger配置，例如文档名称、认证配置等
    options.OperationFilter<SwaggerIgnoreParameterFilter>();
});

• 第四步：给需要隐藏的参数添加标记
  修改你的接口代码，给optional参数加上刚才定义的[SwaggerIgnoreParameter]特性即可：

[HttpGet]
[Route("search")]
[Authorize]
public async Task<IActionResult> Search(string query, [SwaggerIgnoreParameter] string optional = "")
{
   return Ok();
}

注意事项 #

• 该方案仅会从Swagger展示页面移除指定参数，不会影响参数的实际传值、接收逻辑，后端业务代码无需做任何调整
• 后续需要隐藏其他接口的单个参数时，直接给对应参数添加[SwaggerIgnoreParameter]特性即可，无需修改其他配置

内容的提问来源于stack exchange，提问作者paulguy