带有 <example> 标签的数组类型不适用于 Swagger (swashbuckle.aspnetcore)答案

【问题标题】：Array types with <example> tag not working with Swagger (swashbuckle.aspnetcore)带有 <example> 标签的数组类型不适用于 Swagger (swashbuckle.aspnetcore)
【发布时间】：2020-10-06 07:05:45
【问题描述】：

我正在为 swagger 文档使用摘要和示例标签。我的标签有问题，当我使用数组时，它无法被 swagger 识别：

我使用 swashbuckle.aspnetcore 包 Nuget。

例子：

[DataContract]
    public class HeaderResponse
    {
        /// <summary>
        /// Statut code
        /// </summary>
        ///<example>400</example>
        [DataMember]
        public int StatusCode { get; set; }
        /// <summary>
        /// Title
        /// </summary>
        /// <example>Erreur sur methode1</example>
        [DataMember]
        public string Title { get; set; }
        /// <summary>
        /// List of errors 
        /// </summary>
        ///<example>["entry1", "entry2", "entry3"]</example>
        [DataMember]
        public List<string> ErrorList { get; } = new List<string>();
}

在 swagger 文档中，数组没有被解释：

我通过像这样使用 ISchemaFilter 找到了其他解决方案：

public class SwaggerExcludeFilter : ISchemaFilter
    {
        public void Apply(OpenApiSchema schema, SchemaFilterContext context)
        {
            switch (context.Type.Name)
            {
                case "HeaderResponse":
                    foreach (var property in schema.Properties)
                    {
                        if (property.Value.Type == "array")
                        {
                            var array = new OpenApiArray();
                            array.Add(new OpenApiString("item1"));
                            array.Add(new OpenApiString("item2"));
                            array.Add(new OpenApiString("item3"));

                            property.Value.Example = array;
                        }
                    }
                    break;
            }
        }
    }

除了使用ISchemaFilter来处理数组类型的标签，没有别的办法了吗？

【问题讨论】：

标签： c# asp.net-core swagger

【解决方案1】：

您可以尝试这样做：

public List<string> ErrorList { get; } = new List<string>{"entry1", "entry2", "entry3"};

或：

[DataContract]
public class HeaderResponse
{
    public HeaderResponse()
    {
        ErrorList = new List<string> {"entry1", "entry2", "entry3" };
    }
    /// <summary>
    /// Statut code
    /// </summary>
    ///<example>400</example>
    [DataMember]
    public int StatusCode { get; set; }
    /// <summary>
    /// Title
    /// </summary>
    /// <example>Erreur sur methode1</example>
    [DataMember]
    public string Title { get; set; }
    /// <summary>
    /// List of errors 
    /// </summary>
    [DataMember]
    public List<string> ErrorList { get; set; }
}

这是一个演示：

[HttpPost("TestPar")]
        public IActionResult TestPar(HeaderResponse h)
        {
            return Json(h);
        }

结果：

【讨论】：

好的，谢谢，它正在工作，但我不希望通过初始化属性或构造函数来执行此操作。我希望有另一种使用 ISchemaFilter 的解决方案 :)
这个解决方案的问题是您的客户端没有提交错误列表属性的值而不是获取 null 或空数组，您将拥有填充数组，这意味着如果您需要一个非空验证器，它现在必须询问内容并采取相应措施。

【解决方案2】：

我有同样的问题，我试试这个。您可以在属性名称上添加条件并添加 null 返回，以免丢失其他属性的示例。但最好的解决方案是能够找到一个通用的解决方案。如何使用 ISchemaFilter 获取示例标记和属性名称？这是我的解决方案：

public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
    schema.Example = GetExampleOrNullFor(schema, context);
}

private IOpenApiAny GetExampleOrNullFor(OpenApiSchema schema, SchemaFilterContext context)
{

switch (context.Type.Name)
{
    case "MyClass":
        foreach (var property in schema.Properties)
        {
            //Array property, which wraps its elements
            if (property.Value.Type == "array")
            {
                if (property.Key == "MyProperty1")
                {
                    var array = new OpenApiArray();
                    array.Add(new OpenApiString("item1"));
                    array.Add(new OpenApiString("item2"));
                    property.Value.Example = array;
                }
                else if (property.Key == "MyProperty2")
                {
                    var array = new OpenApiArray();
                    array.Add(new OpenApiString("item1"));
                    property.Value.Example = array;
                }
            }
        }
        return null;
    default:
        return null;
}

}

【讨论】：

【解决方案3】：

引号必须使用&quot;进行转义

/// <summary>
/// List of errors 
/// </summary>
///<example>[&quot;entry1&quot;,&quot;entry2&quot;,&quot;entry3&quot;]</example>
[DataMember]
public List<string> ErrorList { get; } = new List<string>();

【讨论】：