Swagger/Swashbuckle 列出可接受的值? [英] Swagger/Swashbuckle list acceptable values?

问题描述

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

I have implemented Swashbuckle/Swagger on my Web API application successfully, but am not happy with the output.

我的一个 web api 方法(企业事件日志记录工具)接受复杂对象值的 JSON 对象.

One of my web api methods (An enterprise event logging tool) accepts a JSON object of a Complex object value.

问题在于，当存在可以使用的可接受值的选定列表时，参数会作为字符串对象列出.我已经设置了默认值，以便如果发送不正确的内容，我将设置为默认值.

The issue is that the parameters are listed as string objects when there is a selected list of acceptable values that can be used. I have set default values so that if something incorrect is sent, I set to default.

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

I guess I could add other service calls that return the acceptable values, but I would rather not.

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

I did implement the schema portion on Swashbuckle to set a valid "example" object, but it only listed one of probably a hundred different combinations.

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

The best example I can give of the problem is below:

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".

The acceptable values for SourceSystem would be something like "Accounting" or "Payments" or "Portal". While the Acceptable values for Company could be "Sub Company 1" or "Partner 1".

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

Is there something I can add to Swashbuckle/Swagger to get this in the output somewhere?

推荐答案

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

The simplest solution would be to to change properties from string type to enum, like:

// 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 没有考虑到这一点.

However enums with spaces are a pain. There is a standard .NET mechanism of handling those (decorating enum members with EnumMember attribute), however swashbuckle doesn't take that into an account.

[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 构建(我可以与之相关)，您可以保持模型原样并实现您的自己的"模式提供程序，如下所示:

So you can get modified version of swashbuckle (with the fix above). Or if you don't want to have custom swashbuckle build (I can relate to that) you can leave your model as it is and implement your "own" schema provider like this:

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 中配置的枚举.以下是快速操作方法:

If I understand your comment you don't have the string as enums configured in web api. Here is quick how-to:

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

这篇关于Swagger/Swashbuckle 列出可接受的值?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！