在 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();
}
相关推荐
稻草猫.4 小时前
Java线程安全:volatile与wait/notify详解
java·后端·idea
IT_陈寒4 小时前
Vite 5年迭代揭秘:3个核心优化让你的项目构建速度提升200%
前端·人工智能·后端
拾贰_C5 小时前
【SpringBoot】前后端联动实现条件查询操作
java·spring boot·后端
catchadmin7 小时前
PHP 快速集成 ChatGPT 用 AI 让你的应用更聪明
人工智能·后端·chatgpt·php
callJJ11 小时前
从 0 开始理解 Spring 的核心思想 —— IoC 和 DI(2)
java·开发语言·后端·spring·ioc·di
你的人类朋友13 小时前
JWT的组成
后端
北风朝向14 小时前
Spring Boot参数校验8大坑与生产级避坑指南
java·spring boot·后端·spring
canonical_entropy14 小时前
一份关于“可逆计算”的认知解码:从技术细节到哲学思辨的完整指南
后端·低代码·deepseek
趙卋傑15 小时前
项目发布部署
linux·服务器·后端·web
数据知道15 小时前
Go基础:Go语言能用到的常用时间处理
开发语言·后端·golang·go语言