Swagger/Swashbuckle列出可接受的值？

Question

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

我的一个web api方法(企业事件记录工具)接受Complex对象值的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来获取输出的某个地方吗？

Answer 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());
  });
}