Swashbuckle(Swagger)中的默认模型示例

Question

我正在运行ASP WebAPI 2并成功安装了Swashbuckle.我试图弄清楚如何定义默认架构值是什么？

例如,在Swagger现场演示站点上,他们将pet的默认值更改为"doggie".他们还定义了状态的允许值.(现场演示)

Answer 1

我设法通过关注此链接上的内容来实现此目的:

https://github.com/domaindrivendev/Swashbuckle/issues/69#issuecomment-53953785

简而言之,这是需要做的事情:

1. 按照链接中的描述创建SwaggerDefaultValue和AddDefaultValues类.我做了一些改变:

   public class SwaggerDefaultValue : Attribute
   {
       public string Name { get; set; }
       public string Value { get; set; }
   
       public SwaggerDefaultValue(string value)
       {
           this.Value = value;
       }
   
       public SwaggerDefaultValue(string name, string value) : this(value)
       {
           this.Name = name;
       }
   }
   
   public class AddDefaultValues : IOperationFilter
   {
       public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
       {
           IDictionary<string, object> parameterValuePairs =
           GetParameterValuePairs(apiDescription.ActionDescriptor);
   
           foreach (var param in operation.parameters)
           {
               var parameterValuePair = parameterValuePairs.FirstOrDefault(p => p.Key.IndexOf(param.name, StringComparison.InvariantCultureIgnoreCase) >= 0);
               param.@default = parameterValuePair.Value;
           }
       }
   
       private IDictionary<string, object> GetParameterValuePairs(HttpActionDescriptor actionDescriptor)
       {
           IDictionary<string, object> parameterValuePairs = new Dictionary<string, object>();
   
           foreach (SwaggerDefaultValue defaultValue in actionDescriptor.GetCustomAttributes<SwaggerDefaultValue>())
           {
               parameterValuePairs.Add(defaultValue.Name, defaultValue.Value);
           }
   
           foreach (var parameter in actionDescriptor.GetParameters())
           {
               if (!parameter.ParameterType.IsPrimitive)
               {
                   foreach (PropertyInfo property in parameter.ParameterType.GetProperties())
                   {
                       var defaultValue = GetDefaultValue(property);
   
                       if (defaultValue != null)
                       {
                            parameterValuePairs.Add(property.Name, defaultValue);
                       }
                   }
               }
           }
   
           return parameterValuePairs;
       }
   
       private static object GetDefaultValue(PropertyInfo property)
       {
           var customAttribute = property.GetCustomAttributes<SwaggerDefaultValue>().FirstOrDefault();
   
           if (customAttribute != null)
           {
               return customAttribute.Value;
           }
   
           return null;
       }
   }
   

   2. 编辑SwaggerConfig并将AddDefaultValues类添加到OperationFilters:

      GlobalConfiguration.Configuration
          .EnableSwagger(c => {
                ...
                c.OperationFilter<AddDefaultValues>()
                ...
           });
      

   3. 现在对于我想要默认值的参数,我只需添加以下内容:

      public IHttpActionResult Put([FromBody]Pet pet)
      {
         ...
         return Ok();
      }
      
      public class Pet {
          [SwaggerDefaultValue("doggie")]
          public string Name { get; set; }
      
          [SwaggerDefaultValue("available")]
          public string Status;
      
          ...
      }
      

Answer 2

那么vgaspar.trivix的代码对我来说不起作用,默认值没有为模式设置.我也有了NullPointerException.我设法通过编辑Apply方法使其按预期工作并操纵schemaRegistry,如下所示:

public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
    if (operation.parameters == null)
        return;
    IDictionary<string, object> parameterValuePairs =
    GetParameterValuePairs(apiDescription.ActionDescriptor);

    foreach (var param in operation.parameters)
    {
        if (param.schema != null && param.schema.@ref != null)
        {
            string schemaName = param.schema.@ref.Split('/').LastOrDefault();
            if (schemaRegistry.Definitions.ContainsKey(schemaName))
                foreach (var props in schemaRegistry.Definitions[schemaName].properties)
                {
                    if (parameterValuePairs.ContainsKey(props.Key))
                        props.Value.@default = parameterValuePairs[props.Key];
                }
        }
        var parameterValuePair = parameterValuePairs.FirstOrDefault(p => p.Key.IndexOf(param.name, StringComparison.InvariantCultureIgnoreCase) >= 0);
        param.@default = parameterValuePair.Value;
    }
}

Answer 3

可以通过ISchemaFilter使用以下方法实现和注册示例模型来定义示例模式:

httpConfig 
    .EnableSwagger(c =>
         {
             c.SchemaFilter<AddSchemaExamples>()
         });

这里提供了一个示例实现:

public class AddSchemaExamples : ISchemaFilter
{
    public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
    {
        if (type == typeof(Product))
        {
            schema.example = new Product
                {
                    Id = 123,
                    Type = ProductType.Book,
                    Description = "Treasure Island",
                    UnitPrice = 10.0M
                };
        }
    }
}

资料来源:https://github.com/domaindrivendev/Swashbuckle/issues/162