.NET Core Web API如何在Swagger文档中集成Display和ErrorMessage特性

默认情况下，Swashbuckle（.NET生态的Swagger实现库）只会识别Required特性的必填标记，不会自动把Display的Name和Required的ErrorMessage同步到swagger.json里。不需要单独创建“显示模型”，通过自定义文档过滤器就能实现需求：

1. 创建自定义文档过滤器类
   这个类负责遍历所有模型属性，提取Display和Required特性的信息，写入Swagger的Schema中：

   using Microsoft.OpenApi.Models;
   using Swashbuckle.AspNetCore.SwaggerGen;
   using System.ComponentModel.DataAnnotations;
   using System.Reflection;
   
   public class CustomSchemaFilter : IDocumentFilter
   {
       public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
       {
           foreach (var schema in swaggerDoc.Components.Schemas)
           {
               // 找到当前Schema对应的实体类型
               var entityType = context.ApiDescriptions
                   .SelectMany(desc => desc.ParameterDescriptions)
                   .Where(p => p.Type.Name.Equals(schema.Key, StringComparison.OrdinalIgnoreCase))
                   .Select(p => p.Type)
                   .FirstOrDefault();
   
               if (entityType == null) continue;
   
               // 遍历Schema的每个属性，匹配实体类的特性
               foreach (var prop in schema.Value.Properties)
               {
                   var propInfo = entityType.GetProperty(prop.Key, BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.Instance);
                   if (propInfo == null) continue;
   
                   // 处理Display特性的Name，写入Schema描述
                   var displayAttr = propInfo.GetCustomAttribute<DisplayAttribute>();
                   if (displayAttr != null)
                   {
                       prop.Value.Description = displayAttr.Name;
                   }
   
                   // 处理Required特性的ErrorMessage，可写入描述或自定义扩展字段
                   var requiredAttr = propInfo.GetCustomAttribute<RequiredAttribute>();
                   if (requiredAttr != null && !string.IsNullOrEmpty(requiredAttr.ErrorMessage))
                   {
                       // 追加提示到描述
                       prop.Value.Description += $"\n必填提示：{requiredAttr.ErrorMessage}";
                       // 或者用OpenAPI规范的自定义扩展字段（以x-开头）单独存储
                       prop.Value.Extensions.Add("x-error-message", new OpenApiString(requiredAttr.ErrorMessage));
                   }
               }
           }
       }
   }
   

2. 注册过滤器到Swagger服务
   在Program.cs（.NET 6+）或Startup.cs中，将自定义过滤器添加到Swagger生成配置里：

   builder.Services.AddSwaggerGen(c =>
   {
       // 注册自定义文档过滤器
       c.DocumentFilter<CustomSchemaFilter>();
       // 其他Swagger配置（比如文档标题、版本等）...
   });
   

3. 验证效果
   重新启动API后，生成的swagger.json会包含对应的信息，示例如下：

   "RouteHeader": {
     "required": [ "routeName" ],
     "properties": {
       "routeName": {
         "type": "string",
         "description": "Service Name\n必填提示：FirstName is mandatory",
         "x-error-message": "FirstName is mandatory"
       }
     }
   }
   

这种方式不需要额外定义单独的显示模型，直接复用现有实体类的特性即可完成Swagger的信息扩展。

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