如何为 Swagger UI 定义参数的默认值？

Question

我已经 Swagger/Swashbuckle 集成到 .NET Core 2.2 API 项目中。一切都很好，我的要求纯粹是为了方便。考虑以下 API 方法：

public Model SomeEstimate(SomeRequest request) {
    return Manager.GetSomeEstimate(request);
}
...
public class SomeRequest {
    public string StreetAddress { get; set; }
    public string Zip { get; set; }
}

当我点击 /swagger/index.html 并想尝试这个 API 时，我总是必须输入 StreetAddress 和 Zip 值。

有没有办法为 StreetAddress 和 Zip 提供默认值？此 answer 建议为 SomeRequest class 的每个属性放置 [DefaultValue("value here")] 属性。它可能适用于常规 .NET，但不适用于 .NET Core。

是否可以为 Swagger UI 提供参数默认值？

Answer 1

要在 .NET Core 中为 Swagger UI 定义参数的默认值，以下 article 为模型 class 中的 DefaultValue 属性定义自定义架构过滤器。下面显示的代码摘自本文，纯粹是为了告知其他有此问题或遇到类似问题的人：

装饰模型中所需的属性：

public class Test {
    [DefaultValue("Hello")]
    public string Text { get; set; }
}

主过滤器：

using System.Collections.Generic;
using System.ComponentModel;
using System.Reflection;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace Project.Swashbuckle {

    public class SchemaFilter : ISchemaFilter {

        public void Apply(Schema schema, SchemaFilterContext context) {
            if (schema.Properties == null) {
                return;
            }

            foreach (PropertyInfo propertyInfo in context.SystemType.GetProperties()) {

                // Look for class attributes that have been decorated with "[DefaultAttribute(...)]".
                DefaultValueAttribute defaultAttribute = propertyInfo
                    .GetCustomAttribute<DefaultValueAttribute>();

                if (defaultAttribute != null) {
                    foreach (KeyValuePair<string, Schema> property in schema.Properties) {

                        // Only assign default value to the proper element.
                        if (ToCamelCase(propertyInfo.Name) == property.Key) {
                            property.Value.Example = defaultAttribute.Value;
                            break;
                        }
                    }
                }
            }
        }

        private string ToCamelCase(string name) {
            return char.ToLowerInvariant(name[0]) + name.Substring(1);
        }
    }
}

最后将其注册到您的 Swagger Options（在 Startup.cs 中）：

services.AddSwaggerGen(c => {
    // ...
    c.SchemaFilter<SchemaFilter>();
});

Answer 2

最初归功于，但如果有人对 .NET Core 3.0+ 感兴趣，Swashbuckle v5.0.0-rc4 会使 SchemaFilter 定义更简单.也许有办法用新属性或类似的东西添加示例值，但我还没有找到这样的方法。

public class SchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (schema.Properties == null)
        {
            return;
        }

        foreach (var property in schema.Properties)
        {
            if (property.Value.Default != null && property.Value.Example == null)
            {
                property.Value.Example = property.Value.Default;
            }
        }
    }
}

Answer 3

Swashbuckle.AspNetCore 5.6.3 只需要 DefaultValueAttribute.

如何为 Swagger UI 定义参数的默认值？

How to define default values for parameters for the Swagger UI?

.net

c#

swagger

.net-core

swashbuckle