如何扩展Swagger UI自定义参数类型/格式的验证（含UUID）

刚好我之前处理过类似的Swagger UI UUID验证自定义需求，给你几个可行的方案，一步步来解决这个问题：

方案1：前端扩展Swagger UI的验证逻辑 #

Swagger UI默认的string/uuid验证是严格遵循RFC带短横线的规则，我们可以直接自定义验证器，让它同时支持带短横线和无短横线的UUID格式：

1. 首先，如果你的Swagger UI是通过Asp.Net Core的UseSwaggerUI配置的，先在项目的wwwroot目录下创建一个自定义脚本文件，比如swagger-custom-validator.js，内容如下：

   // 自定义UUID验证器，支持两种格式
   const customUuidValidator = function(schema, data) {
     // 匹配带短横线（RFC标准）或不带短横线的32位UUID
     const validUuidPattern = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$|^[0-9a-f]{32}$/i;
     if (data && !validUuidPattern.test(data)) {
       return "请输入有效的UUID（支持带短横线或不带短横线格式）";
     }
     return null;
   };
   
   // 初始化Swagger UI时注入自定义验证
   window.addEventListener('load', function() {
     const ui = SwaggerUIBundle({
       url: "/swagger/v1/swagger.json",
       dom_id: '#swagger-ui',
       presets: [
         SwaggerUIBundle.presets.apis,
         SwaggerUIStandalonePreset
       ],
       layout: "StandaloneLayout",
       // 禁用远程验证，使用本地自定义规则
       validatorUrl: null,
       // 覆盖string/uuid的验证逻辑
       customValidators: {
         "string-uuid": customUuidValidator
       }
     });
     window.ui = ui;
   });
   

2. 然后在Asp.Net Core的Startup/Program.cs中配置Swagger UI，注入这个自定义脚本：

   app.UseSwaggerUI(c =>
   {
       c.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API名称 V1");
       // 注入自定义验证脚本
       c.InjectJavascript("/swagger-custom-validator.js");
   });
   

方案2：后端修改Swagger Schema（配合前端验证） #

如果你希望Swagger文档里的参数定义也明确标注支持无短横线UUID，可以在后端通过Swashbuckle的Schema过滤器修改验证规则：

1. 创建一个自定义Schema过滤器类：

   public class UuidSchemaFilter : ISchemaFilter
   {
       public void Apply(OpenApiSchema schema, SchemaFilterContext context)
       {
           // 定位所有类型为string、格式为uuid的Schema
           if (schema.Type == "string" && schema.Format == "uuid")
           {
               // 更新正则表达式，同时支持两种UUID格式
               schema.Pattern = @"^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$|^[0-9a-f]{32}$";
               // 补充描述，提示用户支持两种格式
               schema.Description = string.IsNullOrEmpty(schema.Description) 
                   ? "UUID格式（支持带短横线或不带短横线）" 
                   : $"{schema.Description}（支持带短横线或不带短横线的UUID格式）";
           }
       }
   }
   

2. 在Swashbuckle的配置中注册这个过滤器：

   services.AddSwaggerGen(c =>
   {
       c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
       // 添加自定义Schema过滤器
       c.SchemaFilter<UuidSchemaFilter>();
   });
   

   这样后端生成的Swagger文档里，所有UUID类型的参数都会使用新的验证正则，前端Swagger UI会自动读取这个规则进行验证（如果没有禁用远程验证的话）。

方案3：直接替换Swagger UI的UUID输入组件 #

如果上面的方法还不能满足需求，你可以直接替换Swagger UI内部的JsonSchema_string_uuid组件，完全自定义输入和验证逻辑：

// 在Swagger UI加载前替换组件
SwaggerUIBundle.Components.JsonSchema_string_uuid = {
  template: '<input type="text" class="form-control" ng-model="model.value" ng-keyup="validateInput()">',
  controller: function($scope) {
    $scope.validateInput = function() {
      const uuidRegex = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$|^[0-9a-f]{32}$/i;
      if ($scope.model.value && !uuidRegex.test($scope.model.value)) {
        $scope.model.errors = ["无效的UUID格式，请输入带短横线或不带短横线的32位十六进制字符串"];
      } else {
        $scope.model.errors = [];
      }
    };
    // 初始化时触发一次验证
    $scope.validateInput();
  }
};

把这段代码放到之前的swagger-custom-validator.js里即可，它会完全替换默认的UUID输入组件，用自定义的验证逻辑。

注意事项 #

• 建议同时配合后端和前端的修改，确保前后端的验证规则一致，避免出现“前端过了但后端报错”的情况。
• 测试时要覆盖多种场景：带短横线的合法UUID、无短横线的合法UUID、长度不足的字符串、包含非法字符的字符串，确保验证逻辑准确。

内容的提问来源于stack exchange，提问作者soren.enemaerke