旋转皮带扣.AspNetCore:是否可以为一个参数添加多个示例

Question

我正在使用Swashbuckle。AspNetCore和我想通过XML文档展示一个参数的多个示例。我看到规格允许(https://swagger.io/docs/specification/adding-examples/)，但我似乎不知道如何使用Swashbuckle。AspNetCore。有可能吗？

我尝试了以下方法，

1. <example>"item 1","item 2"</example>
   • 在swagger中，没有添加示例
2. <example>["item 1","item 2"]</example>
   • 我认为只有当参数是一个数组时才应该使用它，所以不要去

Answer 1

CodingMytra提供了链接(https://link.medium.com/bemAjYabHtb)我的问题的答案。

请注意，根据https://swagger.io/docs/specification/adding-examples/，仅参数支持多个示例。

如果出于某些原因(比如我(，您想要显示模式的示例，那么唯一的方法就是在属性的描述中显示它们。下面的例子展示了如何做到这一点

示例属性基类

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = true, Inherited = false)]
public abstract class SwaggerParameterExampleBaseAttribute : Attribute
{ }

[名称，值]示例属性类

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = true, Inherited = false)]
public class SwaggerParameterExampleAttribute : SwaggerParameterExampleBaseAttribute
{
public SwaggerParameterExampleAttribute(string name, string value)
{
Name = name;
Value = value;
}
public SwaggerParameterExampleAttribute(string value)
{
Name = value;
Value = value;
}
public string Name { get; }
public string Value { get; }
}

枚举示例属性类

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = true, Inherited = false)]
public class SwaggerParameterExamplesFromEnumAttribute : SwaggerParameterExampleBaseAttribute
{
public SwaggerParameterExamplesFromEnumAttribute(Type type)
{
if (!type.IsEnum)
throw new ArgumentException("Must be an Enum", nameof(type));
EnumType = type;
}
public Type EnumType { get; }
}

示例过滤器

public class ExampleSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (context.Type.IsClass)
{
foreach (var pi in context.Type.GetProperties())
{
var attribs = pi.GetCustomAttributes<SwaggerParameterExampleBaseAttribute>().ToArray();
if (attribs?.Length > 0)
{
var prop = schema.Properties.FirstOrDefault(x => x.Key.Equals(pi.Name, System.StringComparison.OrdinalIgnoreCase));
if (!prop.Equals(default(KeyValuePair<string, OpenApiSchema>)))
{
var list = new List<string>();
list.AddRange(attribs.OfType<SwaggerParameterExampleAttribute>().Select(x => x.Value));
foreach (var attrib in attribs.OfType<SwaggerParameterExamplesFromEnumAttribute>().ToArray())
{
list.AddRange(Enum.GetNames(attrib.EnumType));
}
prop.Value.Example = new Microsoft.OpenApi.Any.OpenApiString(list.First());
if (list.Count > 1)
{
prop.Value.Description += $"rnrn" +
$"The value can be:rn" +
$"- {string.Join("rn- ", list)}";
}
}
}
}
}
}
}

用法

public class MyClass
{
/// <summary>
/// This is my property
/// </summary>
[SwaggerParameterExample("MyExample1")]
[SwaggerParameterExample("MyExample2")]
[SwaggerParameterExamplesFromEnum(typeof(MyEnum))]
public string MyProperty { get; set; }
}

导致招摇UI

MyClass {
MyProperty   string
example: MyExample1
This is my property
The value can be:
* MyExample1
* MyExample2
* MyEnumString1
* MyEnumString2
}