api 操作参数的 Swashbuckle SchemaFilter

Question

我已成功创建 ISchemaFilter 以扩展 swagger.json 枚举属性定义以用于代码生成目的，如 here 所述。这是我当前的 SchemaFilter.Apply 方法：

public void Apply(Schema schema, SchemaFilterContext context)
{
    if (context.SystemType.IsEnum)
    {
        var names = Enum.GetNames(context.SystemType);
        var values = Enum.GetValues(context.SystemType);
        var desc = "";

        foreach (var value in values)
        {
            var intValue = Convert.ChangeType(value, Enum.GetUnderlyingType(value.GetType()));
            desc += $"{intValue}={value},";
        }
        desc = desc.TrimEnd(',');
        schema.Extensions.Add("x-enumNames", names);
        schema.Extensions["description"] = desc;
    }
}

SchemaFilter 在我的模型定义上正常工作，其中模型 class 具有枚举类型的成员。以下是输出示例：resolution-field，它是枚举类型，注意自定义 x-enumNames 和修改的 description 字段：

resolution: {
    format: "int32",
    enum: [
        1,
        2,
        3,
        4
    ],
    type: "integer",
    x-enumNames: [
        "Hour",
        "Day",
        "Month",
        "Year"
    ],
    description: "1=Hour,2=Day,3=Month,4=Year"
}

问题是 SchemaFilter 没有扩展 操作参数 中的枚举类型。例如下面的 api-method 有参数 resolution:

public async Task<ActionResult<ReturnType>> GetData(Models.ResolutionEnum resolution)

并且这会产生以下对 swagger.json 的操作参数定义（注意缺少 x-EnumNames）：

{
    name: "resolution",
    in: "query",
    required: true,
    type: "integer",
    format: "int32",
    enum: [
        1,
        2,
        3,
        4
    ]
}

是否有任何机制可以扩展作为方法参数一部分的 swagger 枚举模式？

Answer 1

尝试使用 IDocumentFilter，我已经使用它注入 x-stuff，这是一个示例：

public class InjectXStuff : IDocumentFilter
{
    public void Apply(SwaggerDocument s, DocumentFilterContext c)
    {
        PathItem path = s.Paths.Where(x => x.Key.Contains("Values")).First().Value;
        path.Post.Parameters.FirstOrDefault().Extensions.Add("x-stuff", "123456");
    }
}

问题是您需要预先知道路径，不确定您的代码中是否可以使用一种模式来识别那些枚举...

Answer 2

感谢本题下的，发现Swashbuckle.AspNetCore.SwaggerGen命名空间中有多个扩展点。 IParameterFilter 正是我想要的，我能够将 x-enumNames 注入方法参数定义。

以下是我制作的参数过滤器：

public class ModifyParametersFilter : IParameterFilter
{
    public void Apply(IParameter parameter, ParameterFilterContext context)
    {
        var type = context.ParameterInfo?.ParameterType;
        if (type == null)
            return;
        if (type.IsEnum)
        {
            var names = Enum.GetNames(type);
            var values = Enum.GetValues(type);
            var desc = "";

            foreach (var value in values)
            {
                var intValue = Convert.ChangeType(value, Enum.GetUnderlyingType(value.GetType()));
                desc += $"{intValue}={value},";
            }
            desc = desc.TrimEnd(',');
            if (!parameter.Extensions.ContainsKey("x-enumNames"))
                parameter.Extensions.Add("x-enumNames", names);
        }
    }
}

与其他过滤器一样，这可以在 Startup.cs 中使用以下代码段激活：

services.AddSwaggerGen(c =>
{
    ..
    c.ParameterFilter<ModifyParametersFilter>();
}

api 操作参数的 Swashbuckle SchemaFilter

Swashbuckle SchemaFilter for api operation parameters

c#

enums

swagger

swashbuckle

asp.net-core