Question

我想在文档架构中为具有DateTime类型的所有输入参数添加默认描述。这样客户将了解我们使用的是哪种格式等等。

我是否可以为此目的创建ISchemaFilter的自定义实现？

我知道我可以使用xml注释添加描述，但是在这种情况下，我应该将相同的文本复制并粘贴到按日期进行过滤的许多地方。

我尝试为此使用MapType。但是据我所知，它仅适用于响应类型（至少在我的情况下，它仅适用于响应模型）。 I found the similar question ，但仍未得到答案

options.MapType<DateTime> (() => new Schema {
  Type = "string",
  Format = "date-time",
  Description = "Description"
});

我也尝试了自定义的DateTimeSchemaFilter，但是没有为输入参数添加任何描述。我已经尝试了没有xml和/或MapType的配置。在调试模式下，我看到正在调用我的过滤器，但在UI中什么也没有发生。

public class DateTimeSchemaFilter: ISchemaFilter {

    public void Apply(Schema schema, SchemaFilterContext context) 
    {
        var typeInfo = context.SystemType;
        if (typeInfo == typeof(DateTime ? )) 
        {
            schema.Description = "Description";
        }
    }
}

services.AddSwaggerGen(options => {

    options.DescribeAllEnumsAsStrings();

    var xmlFile = $ {Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);

    options.MapType<DateTime> (() => new Schema {
        Type = "string",
        Format = "date-time",
        Description = "Description"
    }); 

    options.SchemaFilter<DateTimeSchemaFilter>();

});

public async Task<IActionResult> GetTelemetries(
        string nodeId, 
        int offset = 0, 
        int limit = DEFAULT_PAGE_LIMIT,
        TelemetryChannel channel = TelemetryChannel.Temperature,
        DateTime? dateFrom = null,
        DateTime? dateTo = null)
    {
        var result = await _telemetryService.GetTelemetries(nodeId, offset, limit);

        return BaseResponse(result);
    }

Here is my Swagger documentation output

Answer 1

如果您有自定义架构过滤器...

public class DateTimeSchemaFilter: ISchemaFilter {

    public void Apply(Schema schema, SchemaFilterContext context) 
    {
        var typeInfo = context.SystemType;
        if (typeInfo == typeof(DateTime ? )) 
        {
            schema.Description = "Description";
        }
    }
}

...您可以使用以下注释进行注册：

[SwaggerSchemaFilter(typeof(DateTimeSchemaFilter))]
public class YourModel
{
    public int Description { get; set; }
}

注释可以通过NuGet软件包获得：https://www.nuget.org/packages/Swashbuckle.AspNetCore.Annotations

您需要在swagger生成器（Startup.cs）中注册注释：

services.AddSwaggerGen(x =>
{
   x.EnableAnnotations();
});

Answer 2

我遇到了同样的问题-我设置了一个ISchemaFilter来填充描述（就我而言，我是基于属性的存在来进行描述的）。

我可以看到我的过滤器被调用并设置了描述，但是当我查看SwaggerUI / OpenAPI规范文件时，描述丢失了。

结果证明它已被代码破坏，以包含XML注释，即

                foreach (var assembly in new[] { typeof(SomeType).Assembly, typeof(AnotherType).Assembly })
                {
                    var filePath = Path.Combine(AppContext.BaseDirectory, $"{assembly.GetName().Name}.xml");
                    c.IncludeXmlComments(filePath, true);
                }

当我将模式过滤器注册移到XemComments之类的东西之后（隐式添加了一个模式过滤器），一切都按预期工作了。

注意：更新描述时请多加注意，也许您想附加到描述（如果非空）而不是覆盖它。

使用Swashbuckle ISchemaFilter设置输入参数的默认描述

2 个答案: