Swagger Swashbuckle Asp.NET Core：显示使用的每个枚举的详细信息

Posted 2023-03-31

【中文标题】Swagger Swashbuckle Asp.NET Core：显示使用的每个枚举的详细信息

【英文标题】：Swagger Swashbuckle Asp.NET Core: show details about every enum is used

【发布时间】：2020-12-15 19:07:51

【问题描述】：

我有以下枚举：

public enum TicketQuestionType

    General = 1,
    Billing = 2,
    TMS = 3,
    HOS = 4,
    DeviceManagement = 5

和模型类：

public class TicketCreateApi

    public string Subject  get; set; 
    public TicketQuestionType QuestionType  get; set;  = TicketQuestionType.General;
    public TicketType Type  get; set;  = TicketType.Problem;
    public TicketStatus Status  get; set;  = TicketStatus.New;
    public TicketPriority Priority  get; set;  = TicketPriority.Normal;
    public string Description  get; set; 
    public List<string> Attachments  get; set; 
    public int? DeviceId  get; set; 
    public int? DriverId  get; set; 

我的 API 方法使用它：

Task<IActionResult> Create(TicketCreateApi model);

Swagger 生成以下内容：

还有这个：

所以，我们只能看到默认值，而无法看到可用的枚举列表（名称和值）。 我想展示它。怎么做？

【参考方案1】：

我们只能看到默认值，无法看到可用的枚举列表 （名称和值）。我想展示它。怎么做？

要在 swagger 中将枚举显示为字符串，请配置 JsonStringEnumConverter，在 ConfigureServices 中添加以下行：

        services.AddControllers().AddJsonOptions(options =>
            options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()));

输出如下：

如果您想将枚举显示为 stings 和 int 值，您可以尝试创建一个 EnumSchemaFilter 来更改架构。代码如下：

public class EnumSchemaFilter : ISchemaFilter

    public void Apply(OpenApiSchema model, SchemaFilterContext context)
    
        if (context.Type.IsEnum)
        
            model.Enum.Clear();
            Enum.GetNames(context.Type)
                .ToList()
                .ForEach(name => model.Enum.Add(new OpenApiString($"Convert.ToInt64(Enum.Parse(context.Type, name)) = name")));
        
    

将 SwaggerGen 配置为在 ShemaFilter 之上使用。

        services.AddSwaggerGen(c =>
        
            c.SwaggerDoc("v1", new OpenApiInfo
            
                Version = "v1",
                Title = "ToDo API",
                Description = "A simple example ASP.NET Core Web API",
                TermsOfService = new Uri("https://example.com/terms"),
                Contact = new OpenApiContact
                
                    Name = "Shayne Boyer",
                    Email = string.Empty,
                    Url = new Uri("https://twitter.com/spboyer"),
                ,
                License = new OpenApiLicense
                
                    Name = "Use under LICX",
                    Url = new Uri("https://example.com/license"),
                
            );
              
            c.SchemaFilter<EnumSchemaFilter>();
        );

结果如下：

【参考方案2】：

我试过 EnumSchemaFilter。每次提交请求时我都会遇到一些错误。 因为序列化枚举字符串为int

我使用了这个代码块，我希望它能工作

services.AddControllersWithViews()
                    .AddJsonOptions(
                        opts =>
                        
                            var enumConverter = new JsonStringEnumConverter();
                            opts.JsonSerializerOptions.Converters.Add(enumConverter);
                        );