Swashbuckle - 在招摇文档中将字符串视为枚举

Posted 2023-03-28

【中文标题】Swashbuckle - 在招摇文档中将字符串视为枚举

【英文标题】：Swashbuckle - treat string as enum in swagger documentation

【发布时间】：2019-06-14 16:37:30

【问题描述】：

我正在使用 FluentValidation，我只想从 fluent 验证器接收我的自定义错误。这就是为什么我在请求类中的所有属性都是字符串的原因。但是，我也希望有更好的枚举类型文档。

这是我的示例请求：

 public class AddNewPaymentRequest
 
     [EnumDataType(typeof(PaymentStatus))]
     public string PaymentStatus  get; set; 

     public string Id  get; set; 
 

和示例枚举：

 public enum PaymentStatus
 
     Unknown,
     New,
     Pending,
     Completed
 

和控制器：

[HttpPost]
public async Task<ActionResult> PostAsync([FromBody] AddNewPaymentRequest request)

   ...

我想让这个 EnumDataType 作为 Swagger 显示枚举描述的信息，而不是字符串 destrction。我希望 Swagger 将此字符串视为枚举。

实际结果： click

预期结果： click

有没有可能以这种方式配置 Swashbuckle？

【问题讨论】：

你解决了吗？或者你按照下面的答案？

不是，我想尝试用 int 而不是 string 解决它

【参考方案1】：

我猜我们说的是 .NET Core

如果你没问题，可以将其明确定义为枚举而不是字符串

 public class AddNewPaymentRequest
 
     //[EnumDataType(typeof(PaymentStatus))]
     //public string PaymentStatus  get; set; 

     public PaymentStatus PaymentStatus  get; set; 

     public string Id  get; set; 
 

然后您可以定义 SwaggerGen 如何处理枚举

 services.AddSwaggerGen(c => c.DescribeAllEnumsAsStrings();  );

如果您在通过您的 api 接收/发送数据时遇到序列化/反序列化枚举（由 Newtonsoft.Json 编写）的问题，您可以对转换采取更多控制器（如有必要）

 [Newtonsoft.Json.JsonConverter(typeof(Newtonsoft.Json.Converters.StringEnumConverter))]
 public enum PaymentStatus
 
     [EnumMember(Value = "Unknwon")]
     Unknown,

     [EnumMember(Value = "New")]
     New,

     [EnumMember(Value = "Pending")]
     Pending,

     [EnumMember(Value = "Completed")]
     Completed,

     [EnumMember(Value = "something_different_with_underline")]
     SomethingDifferentWithUnderline
 

请注意，这些枚举的 ToString() 可能会导致不同的字符串（带/不带）下划线

【讨论】：

有没有办法用 INT 做到这一点？

Swashbuckle 的方法 DescribeAllEnumsAsStrings() 已过时。你应该配置你的序列化器，swagger 会自动使用它。

【参考方案2】：

Swaggers 仅支持 RequiredAttribute、ObsoleteAttribute 和 MetaData（用于外部类）。 所以除了写这样的东西之外，没有办法描述公认的价值观：

/// <summary> Allowed values are....

【讨论】：

我们在 Swashbuckle 中有以下内容吗？ swagger.io/docs/specification/data-models/enums

@tnk479 - 我说的是描述 API 的 C# 代码。后来它被用来生成 Swagger 的文档和 OpenApi。