Использование Swashbuckle ISchemaFilter для установки описания по умолчанию входных параметров - PullRequest
Новая
       39

Использование Swashbuckle ISchemaFilter для установки описания по умолчанию входных параметров

0 голосов
/ 08 июля 2019

Я хочу добавить описание по умолчанию в схему документации для всех входных параметров с типом DateTime.Таким образом, клиенты поймут, какие форматы мы используем и т. Д.

Могу ли я создать свою собственную реализацию ISchemaFilter для этих целей?

Я знаю, что могу добавить описание, используя комментарии xml, но вВ этом случае я должен скопировать и вставить один и тот же текст во многих местах, где у меня есть фильтр по дате.

Я пытался использовать MapType для этого.Но, насколько я понимаю, это работает только для типов ответов (по крайней мере, в моем случае это работает только для моделей ответов). Я нашел похожий вопрос , но он все еще остается без ответа 

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

Я также попробовал свой собственный DateTimeSchemaFilter, но описания для моих входных параметров не были добавлены.Я уже пробовал конфигурацию без XML и / или MapType.В режиме отладки я вижу, что мой фильтр вызывается, но в интерфейсе ничего не происходит.

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);
    }

Вот мой вывод документации по Swagger

1 Ответ

0 голосов
/ 08 июля 2019

Если у вас есть собственный фильтр схемы ... 

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();
});
...