Swagger/Swashbuckle 列出可接受的值？

Posted 2023-03-31

【中文标题】Swagger/Swashbuckle 列出可接受的值？

【英文标题】：Swagger/Swashbuckle list acceptable values?

【发布时间】：2015-11-27 01:38:25

【问题描述】：

我已在我的 Web API 应用程序上成功实现了 Swashbuckle/Swagger，但对输出不满意。

我的一个 web api 方法（一个企业事件记录工具）接受一个复杂对象值的 JSON 对象。

问题在于，当存在可以使用的可接受值的选定列表时，参数被列为字符串对象。我设置了默认值，因此如果发送了不正确的内容，我设置为默认值。

我想我可以添加其他返回可接受值的服务调用，但我宁愿不这样做。

我确实在 Swashbuckle 上实现了架构部分来设置一个有效的“示例”对象，但它只列出了可能一百种不同组合中的一种。

我能给出的最好的例子如下：

EnterpriseEvent 
   EventType (string, optional),
   SourceSystem (string, optional),
   Company (string, optional),
   Interface (string, optional),
   TransactionType (string, optional),
   EventDateTime (string, optional),
   EventXML (Array[Object], optional),
   Operation (string, optional),
   LoggingLevel (string, optional)

SourceSystem 可接受的值类似于“Accounting”或“Payments”或“Portal”。而公司的可接受值可能是“子公司 1”或“合作伙伴 1”。

有什么我可以添加到 Swashbuckle/Swagger 以在某处的输出中得到它的东西吗？

【问题讨论】：

我也有同样的问题。我已经实现了一些 API 方法的多个版本，一个带有 URI 参数，一个带有 Json 在方法体中，只是为了测试。在 URI 中带有参数的那个记录得很好，带有枚举下拉列表和所有内容，但是 JSON 只显示一个带有字符串的 Json 示例。

【参考方案1】：

最简单的解决方案是将属性从字符串类型更改为枚举，例如：

// original    
public class EnterpriseEvent 
   public string SourceSystem  get; set; 


// change
 public class EnterpriseEvent 
   public SourceSystemType SourceSystem  get; set; 

public enum SourceSystemType   
   Accounting,
   Payments
   

但是，带有空格的枚举很痛苦。有一个标准的 .NET 机制来处理这些（使用 EnumMember 属性装饰枚举成员），但是 swashbuckle 没有考虑到这一点。

[DataContract]
public enum CompanyType

    [EnumMember(Value = "Partner 1")]
    Partner1,
    [EnumMember(Value = "Sub Company 1")]
    SubCompany1

见https://github.com/domaindrivendev/Swashbuckle/pull/563/files

因此您可以获得修改版的 swashbuckle（带有上述修复）。或者，如果您不想自定义 swashbuckle 构建（我可以与之相关），您可以保留模型原样并实现您的“自己的”模式提供程序，如下所示：

GlobalConfiguration.Configuration 
  .EnableSwagger(c =>
  
    c.CustomProvider((defaultProvider) => new CustomSwaggerProvider(defaultProvider));
  );       

public class CustomSwaggerProvider: ISwaggerProvider

  private readonly ISwaggerProvider m_DefaultProvider;
  public CustomSwaggerProvider(ISwaggerProvider defaultProvider)
  
    m_DefaultProvider = defaultProvider;
  

  public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
  
    // grab the default schema
    var result = m_DefaultProvider.GetSwagger(rootUrl, apiVersion);
    // adjust
    result.definitions["EnterpriseEvent"]
     .properties["SourceSystem"]
     .@enum = new string[]  "Enum with space 1", "Enum with space 2" ;

    return result;
  

编辑：

如果我理解您的评论，您没有将字符串作为 Web api 中配置的枚举。以下是快速操作方法：

protected void Application_Start() 
  GlobalConfiguration.Configure((config) => 
    config.Formatters.JsonFormatter.SerializerSettings.Converters.Add(
      new Newtonsoft.Json.Converters.StringEnumConverter());
  );

【讨论】：

问题是 JSON 服务不显示允许的值，即使你使用 Enums

这里可能有更好的解释。你的 StringEnumConverter 也会解决这个问题吗？ ***.com/questions/34632729/…

可能值得编辑它以反映似乎链接到句柄 EnumMember 的拉取请求似乎已合并到当前的 swashbuckle 版本中？

这也不能完全工作，因为没有简单的方法来验证传入到使用枚举的端点的数据是否正确——您总是会看到默认的枚举值。甚至垃圾也会被丢弃，因此该属性的值是第一个枚举值。您可以通过检查模型状态来捕获它，但这是一个无法轻松替换的预烘焙错误（而且错误消息很糟糕）。