目录1. 核心原理2. 实现步骤第一步定义枚举及描述可选第二步创建扩展方法获取描述第三步实现 ISchemaFilter第四步注册 Filter3. 替代方案全局序列化设置总结如果您喜欢此文章请收藏、点赞、评论谢谢祝您快乐每一天。在 C# ASP.NET Core 项目中若希望通过 ISchemaFilter 自定义 SwaggerOpenAPI文档中枚举的显示方式例如显示枚举名称、描述或格式化字符串可以通过实现 ISchemaFilter 接口来修改 OpenApiSchema 的属性。以下是具体的实现步骤和代码示例1. 核心原理ISchemaFilter 允许在生成 Swagger Schema 时介入处理。当检测到类型是枚举enum时可以读取枚举的值、名称以及附加的特性如 [Description]然后将其格式化为字符串赋值给 schema.Description 或 schema.Enum 相关的显示字段。2. 实现步骤第一步定义枚举及描述可选为了让 Swagger 显示更友好的文本通常配合 [Description] 特性使用。using System.ComponentModel;public enum UserStatus{[Description(激活状态)]Active 1,[Description(禁用状态)]Disabled 2,[Description(待审核)]Pending 3}第二步创建扩展方法获取描述为了方便读取 [Description] 特性可以编写一个扩展方法。using System;using System.ComponentModel;using System.Reflection;public static class EnumExtensions{public static string GetDescription(this Enum value){FieldInfo field value.GetType().GetField(value.ToString());if (field ! null){DescriptionAttribute attribute (DescriptionAttribute)Attribute.GetCustomAttribute(field, typeof(DescriptionAttribute));if (attribute ! null){return attribute.Description;}}return value.ToString(); // 如果没有描述返回枚举名称}}第三步实现 ISchemaFilter创建一个类实现 ISchemaFilter 接口。在该类中判断当前处理的类型是否为枚举如果是则构建自定义的描述字符串。using Microsoft.OpenApi.Models;using Swashbuckle.AspNetCore.SwaggerGen;using System;using System.Text;public class EnumSchemaFilter : ISchemaFilter{public void Apply(OpenApiSchema schema, SchemaFilterContext context){// 判断当前类型是否为枚举if (context.Type.IsEnum){StringBuilder sb new StringBuilder();// 获取所有枚举名称var names Enum.GetNames(context.Type);foreach (var name in names){// 解析枚举值var enumValue Enum.Parse(context.Type, name);var intValue Convert.ToInt64(enumValue);// 获取描述文本var description ((Enum)enumValue).GetDescription();// 格式化输出例如: Active (激活状态) 1sb.AppendLine(${name} ({description}) {intValue});}// 将格式化后的字符串赋值给 Schema 的 Description// 注意这会覆盖原有的 XML 注释描述如果需要保留可以先读取原有 Description 并拼接schema.Description sb.ToString();// 可选如果你希望 Swagger UI 的下拉框直接显示字符串而不是数字// 通常需要配合 JsonStringEnumConverter 使用但 ISchemaFilter 主要用于文档展示。// 某些情况下也可以尝试修改 schema.Enum 为字符串列表但这可能影响客户端代码生成。}}}第四步注册 Filter在 Program.cs 或 Startup.cs 中配置 Swagger 时添加该 Filter。ASP.NET Core 6 (Program.cs):builder.Services.AddSwaggerGen(c {c.SwaggerDoc(v1, new() { Title My API, Version v1 });// 注册自定义的 Enum Schema Filterc.SchemaFilterEnumSchemaFilter();// 如果还需要显示 XML 注释记得包含 XML 文件路径// var xmlFile ${Assembly.GetExecutingAssembly().GetName().Name}.xml;// var xmlPath Path.Combine(AppContext.BaseDirectory, xmlFile);// c.IncludeXmlComments(xmlPath);});3. 替代方案全局序列化设置如果目标不仅仅是 Swagger 文档显示而是希望 API 返回的 JSON 中枚举也显示为字符串而非数字则应配置 JSON 序列化器这通常比 ISchemaFilter 更根本地解决问题。使用 System.Text.Json:builder.Services.AddControllers().AddJsonOptions(options {options.JsonSerializerOptions.Converters.Add(new System.Text.Json.Serialization.JsonStringEnumConverter());});使用 Newtonsoft.Json:builder.Services.AddControllers().AddNewtonsoftJson(options {options.SerializerSettings.Converters.Add(new Newtonsoft.Json.Converters.StringEnumConverter());});注意仅配置序列化转换器通常会让 Swagger 自动识别并显示枚举的字符串值但在某些旧版本或特定配置下可能需要结合 ISchemaFilter 来优化文档中的可读性描述。总结仅优化文档显示使用 ISchemaFilter 修改 schema.Description展示“名称 (描述) 值”的格式。改变 API 行为及文档配置 JsonStringEnumConverter使 JSON 输出和 Swagger 示例均使用字符串表示枚举。如果您喜欢此文章请收藏、点赞、评论谢谢祝您快乐每一天。