.NET Разработчик on Telegram: “День 1996. #ЗаметкиНаПолях Кастомизируем Swagger…”

День 1996. #ЗаметкиНаПолях
Кастомизируем Swagger UI
Swagger — это набор инструментов для разработки, документирования и использования RESTful API. Он помогает разработчикам более эффективно проектировать, создавать, документировать и использовать API.

Swashbuckle — проект с открытым кодом, который интегрирует Swagger с приложениями .NET. По умолчанию при создании проекта API в Program.cs создаётся код, который добавляет поддержку Swagger вместе со Swagger UI.

builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
  app.UseSwagger();
  app.UseSwaggerUI();
}

Этот UI можно обогатить множеством вещей.

IDocumentFilter
С помощью этого интерфейса можно манипулировать и настраивать весь документ Swagger/OpenAPI перед его визуализацией или доставкой клиентам. Он обеспечивает возможность изменять, добавлять или удалять любую часть документа, например пути, операции, схемы и т. д.

Метод Apply предоставляет доступ к объекту OpenApiDocument, который представляет собой документ Swagger, и объекту DocumentFilterContext, который предоставляет дополнительный контекст и информацию.

Например, вам нужно удалить устаревшую конечную точку из Swagger UI, не удаляя её из кода. Если мы пометим какую-то конечную точку как устаревшую (Deprecated), это не скроет её из Swagger UI. Она будет просто перечёркнута и выделена серым цветом.

public class RemoveObsoleteFilter : IDocumentFilter
{
  public void Apply(
   OpenApiDocument doc, 
   DocumentFilterContext ctx) {
    var obsPaths = doc.Paths
         .Where(p => p.Value.Operations
           .Any(op => op.Value.Deprecated))
         .Select(p => p.Key)
         .ToList();

    foreach (var path in obsPaths)
      doc.Paths.Remove(path);
  }
}

Добавим фильтр в Program.cs:

builder.Services.AddSwaggerGen(c =>
{
  c.DocumentFilter<RemoveObsoleteFilter>();
});

Теперь эта конечная точка не появится в Swagger UI.

Также можно добавить дополнительные метаданные ко всем (или избранным) конечным точкам. Например, добавление стандартного заголовка полезно для ограничения скорости, отслеживания запросов или любых других сквозных задач:

public class CustomHeaderFilter : IDocumentFilter
{
  public void Apply(
   OpenApiDocument doc, 
   DocumentFilterContext ctx)
  {
    foreach (var path in doc.Paths.Values)
    {
      foreach (var op in path.Operations.Values)
      {
        foreach (var resp in op.Responses.Values)
        {
          resp.Headers ??= 
            new Dictionary<string, OpenApiHeader>();
                
          resp.Headers
           .Add("X-Custom-Header", 
            new OpenApiHeader
            {
              Description = "Custom header",
              Schema = new OpenApiSchema
              {
                Type = "string"
              }
            });
        }
      }
    }
  }
}

Источник: https://thecodeman.net/blog