.NET6 Swashbuckle路径/单值查询枚举信息缺失问题咨询

• 技术栈：基于C# .NET 6开发API项目，使用Swashbuckle生成供客户端调用的Swagger接口文档
• 依赖版本：已安装Swashbuckle.AspNetCore 6.3.1、Swashbuckle.AspNetCore.Filters 7.0.2
• 全局枚举规则：项目所有枚举均采用字符串序列化规则

Startup.cs中已完成如下基础配置：

// Swagger基础配置
swaggerOptions.UseInlineDefinitionsForEnums();
swaggerOptions.SchemaFilter<EnumDescriptionFilter>(); // 自定义枚举说明过滤器

// JSON序列化配置
.AddJsonOptions(options =>
{
    options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
})

• 枚举作为查询字符串参数时，仅List<枚举类型>集合参数可正常展示枚举可选值；单值[FromQuery] 枚举类型参数会显示为无类型状态
• 枚举作为路径参数时，Swagger无法正常展示枚举相关说明、可选值列表
• 手动将路径参数类型声明为string后，Swagger仅将其识别为普通字符串类型，不会展示枚举可选值列表
• 已尝试调整Swagger基础配置、引入Annotations包、切换至Newtonsoft序列化等方案，均未解决问题
• 根因确认：该问题属于OpenAPI.NET已知Bug，官方给出的临时规避方案为配置swaggerGenOptions.UseInlineDefinitionsForEnums();，但该方案无法覆盖路径参数、单值查询枚举参数场景

通过自定义IOperationFilter，统一修正所有路径参数、查询参数中的枚举类型Schema，手动注入枚举可选值与说明，彻底解决该问题，具体操作如下：

1. 编写自定义枚举参数修复过滤器

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Linq;

public class EnumParameterFixFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null) return;

        foreach (var parameter in operation.Parameters)
        {
            // 匹配当前接口的实际参数定义
            var apiParameter = context.ApiDescription.ParameterDescriptions
                .FirstOrDefault(p => p.Name.Equals(parameter.Name, StringComparison.OrdinalIgnoreCase));
            if (apiParameter == null) continue;

            // 处理普通枚举、可空枚举类型
            var paramType = apiParameter.Type;
            var enumType = Nullable.GetUnderlyingType(paramType) ?? paramType;
            if (!enumType.IsEnum) continue;

            // 手动构造枚举Schema，填充可选值列表
            parameter.Schema = new OpenApiSchema
            {
                Type = "string",
                Enum = Enum.GetNames(enumType)
                    .Select(enumName => new OpenApiString(enumName) as IOpenApiAny)
                    .ToList()
            };

            // 补充参数说明，可结合原有自定义枚举过滤器扩展显示中文描述
            parameter.Description = $"可选枚举值：{string.Join("、", Enum.GetNames(enumType))}";
        }
    }
}

2. 在Swagger生成配置中注册该过滤器，注意需放在UseInlineDefinitionsForEnums()配置之后

services.AddSwaggerGen(c =>
{
    // 原有配置保留
    c.UseInlineDefinitionsForEnums();
    c.SchemaFilter<EnumDescriptionFilter>();
    
    // 注册自定义枚举参数修复过滤器
    c.OperationFilter<EnumParameterFixFilter>();
});

修复后效果 #

• 路径参数中的单值枚举可正常展示下拉可选值列表，类型正确识别为字符串枚举
• 查询参数中的单值枚举不再显示为无类型状态，和集合枚举参数展示效果完全一致
• 兼容可空枚举类型、原有自定义枚举描述逻辑，不影响请求/响应体中的枚举序列化规则

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