在 swagger 中支持 asp.net core 可选路由参数

场景

  • 同一个 Controller 可能对不同环境有不同的行为,通过路由的 env 参数调整注入的参数

  • 每一次请求上下文可能会根据 env 的值修改 repo 的具体参数

  • 系统会提供默认的 env, 因此此处的路由参数为可选参数

  • swagger 根据 OpenApi v3.x 规范,即使使用 ? 标注为可选,ui 中仍然为 required

    C# 复制代码
    [Route("api/{env:env?}/[controller]")]
    [ApiController]
    public class DemoController(IDemoRepo repo) : ControllerBase
    {
        /* other codes */
    }

解决方法

  • 增加自定的方法修改已经生成的 swagger 文档
C# 复制代码
builder.Services.AddSwaggerGen(opt =>
{
   opt.OperationFilter<ApplyOptionalRouteParameterOperationFilter>();
   /* other codes */
}

public partial class ApplyOptionalRouteParameterOperationFilter : IOperationFilter
{
   public void Apply(OpenApiOperation operation, OperationFilterContext context)
   {
       if (operation.Parameters.Count == 0) return;
       // 获取方法以及类上面的 RouteAttribute
       var attrs = context.MethodInfo.GetCustomAttributes(true)
           .Concat(context.MethodInfo.DeclaringType?.GetCustomAttributes(true) ?? [])
           .OfType<RouteAttribute>().Where(x => x.Template.Contains('?')).ToList();
           
       // 遍历所有 RouteAttribute,如果包含可选参数,则对应修改 OpenAPI 参数定义
       foreach (var route in attrs)
       {
           var matches = RouteTemplateRegex().Matches(route.Template);
           foreach (Match match in matches)
           {
               var name = match.Groups["name"].Value;
               var parameter = operation.Parameters.FirstOrDefault(x => x.Name == name);
               if (parameter is not null)
               {
                   parameter.AllowEmptyValue = true;
                   parameter.Required = false;
                   parameter.Schema.Nullable = true;
               }
           }
       }
   }

   [GeneratedRegex(@"\{(?<name>\w+)(\:\w+)*\?\}")]
   private static partial Regex RouteTemplateRegex();
}
相关推荐
xuxie138 分钟前
SpringBoot文件下载(多文件以zip形式,单文件格式不变)
java·spring boot·后端
重生成为编程大王34 分钟前
Java中的多态有什么用?
java·后端
FL16238631292 小时前
Windows Server2012 R2 安装.NET Framework 3.5
.net
Funcy2 小时前
XxlJob 源码分析03:执行器启动流程
后端
豌豆花下猫3 小时前
Python 潮流周刊#118:Python 异步为何不够流行?(摘要)
后端·python·ai
秋难降4 小时前
SQL 索引突然 “罢工”?快来看看为什么
数据库·后端·sql
Access开发易登软件5 小时前
Access开发导出PDF的N种姿势,你get了吗?
后端·低代码·pdf·excel·vba·access·access开发
中国胖子风清扬5 小时前
Rust 序列化技术全解析:从基础到实战
开发语言·c++·spring boot·vscode·后端·中间件·rust
CodeCraft Studio6 小时前
Aspose.Words for .NET 25.7:支持自建大语言模型(LLM),实现更安全灵活的AI文档处理功能
人工智能·ai·语言模型·llm·.net·智能文档处理·aspose.word
bobz9656 小时前
分析 docker.service 和 docker.socket 这两个服务各自的作用
后端