С выходом .NET 9 пакет Swashbuckle.AspNetCore выпилили из шаблона Web API. Это означает, что при создании нового приложения ASP.NET Core Web API у нас больше нет привычного зеленого пользовательского интерфейса Swagger для тестирования endpoint-ов. В статье — краткий разбор, почему это произошло, и обзор альтернативы Scalar.

Что не так со Swagger в .NET

Раньше, чтобы создать документацию OpenAPI в ASP.NET Core, многие пользовались Swashbuckle. Это было настолько популярным решением, что Microsoft включила его в дефолтные шаблоны Web API.

Но в какой-то момент основные разработчики Swashbuckle покинули проект и начались трудности: копился техдолг, и запоздалая поддержка .NET 8 привела к проблемам совместимости. Тогда Microsoft засомневались, что продукт будет развиваться и вовремя поддерживать новые версии .NET.

Чтобы перестраховаться, Microsoft отказались от Swashbuckle и сделали собственное решение — ведь поддерживать и интегрировать своё проще, чем чужое. Теперь при создании решения в .NET 9 из шаблона Web API в проекте будет пакет Microsoft.AspNetCore.OpenApi.

С пакетом OpenApi разработчики получили больше собственных способов тестирования и документирования API. Например, теперь есть поддержка файлов .http в Visual Studio и Endpoints Explorer. Это делает Swagger UI менее необходимым.

Прочитать мнение Microsoft по этому поводу

А что, Swagger больше совсем не работает?

Пакет Swashbuckle.AspNetCore доступен, его можно установить, и нет предпосылок к тому, что это изменится. Проблема в том, что проект развивается крайне медленно и не успевает за новыми фичами ASP.NET Core.

Но для тех, кто хочет продолжать использовать Swagger, есть целых два способа. Первый — заменить пакет Microsoft.AspNetCore.OpenApi на Swashbuckle.AspNetCore. Затем добавить привычные вызовы.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSwaggerGen();
var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();
app.MapGet("/", => "Hello World!");
app.Run();

Тогда OpenAPI-спецификация будет генерироваться с помощью библиотеки Swashbuckle как и раньше.

Второй способ — оставить пакет Microsoft.AspNetCore.OpenApi для генерации спецификации, а подключить только Swagger UI.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi();
app.UseSwaggerUI(o => 
  o.SwaggerEndpoint("/openapi/v1.json", "v1"));
app.MapGet("/", => "Hello World!");
app.Run();

В этом случае при вызове UseSwaggerUI важно указать путь для файла со спецификацией.

Немного про настройку OpenAPI

Генерацию спецификации через пакет OpenApi можно гибко настраивать, как и при Swagger. Вот основные значения, которые можно указать:

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info.Version = "Версия документа OpenAPI";
        document.Info.Title = "Заголовок";
        document.Info.Description = "Описание";
        document.Info.TermsOfService = new Uri("https://mycompany.com/terms");
        document.Info.Contact = new OpenApiContact
        {
            Name = "Ivan Ivanov",
            Email = "iivanov@mycompany.com",
            Url = new Uri("https://habr.com/")
        };
      
        document.Info.License = new OpenApiLicense
        {
            Name = "MIT License",
            Url = new Uri("https://opensource.org/licenses/MIT")
        };

        //Информация о подключении к целевому серверу
        document.Servers.Add(new OpenApiServer
        {
            Url = "https://my.app.com/v1",
            Description = "Описание для хоста"
        });
      
        return Task.CompletedTask;
    });
});

Можно настроить метаданные OpenAPI для endpoint-ов Minimal API в ASP.NET Core:

app.MapGet("/{answer}",
    (
        [Description("Your answer.")]
        [DefaultValue("42")]
        string answer
    ) => Results.Ok(new { Message = $"Answer: {answer}!" }))
    .WithName("GetAnswer")  // Идентификатор операции
    .WithSummary("Answer to the Question.")  // Заголовок
    .WithDescription("Answer to the Ultimate Question of Life, the Universe, and Everything.")  // Полное описание
    .WithTags("DeepThought")  // Теги для категоризации
    .Produces<object>(200)  // Статус ответа 200 и возвращаемый тип данных
    .Produces(400)  // Статус ответа 400
    .ProducesProblem(500)  // Статус ответа 500 при неуспешной операции
    .RequireAuthorization();  // Необходимость авторизации

Scalar как альтернатива SwaggerUI

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

Счётчик скачивания пакетов и больше 10K звезд на GitHub наводят на мысль, что в сообществе .NET его всё чаще выбирают как альтернативу SwaggerUI.

У Scalar более современный и удобный дизайн, его проще настраивать. Есть мощная функция генерации клиентского кода для различных языков программирования. А ещё с ним легко добавлять или изменять файлы cookie, заголовки и параметры при работе с запросами.

Начало работы со Scalar

Первым делом необходимо добавить nuget-пакет Scalar.AspNetCore. А затем подключить Scalar в Program.cs:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

Ещё можно изменить файл launchSettings.json, чтобы Scalar UI запускался сразу после старта приложения.

"https": {
  "commandName": "Project",
  "launchBrowser": true,
  "launchUrl": "scalar/v1",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}

Этого достаточно, чтобы при запуске приложения по пути /scalar/v1 открывалась соответствующая страница.

Слева отображаются все сгруппированные по тегам endpoint-ы и все модели. На моём скриншоте виден единственный endpoint и относящаяся к нему модель ProblemDetails. На основной части страницы отображается информация о приложении, полученная из OpenAPI-схемы. Есть поиск с удобной навигацией по endpoint-ам и моделям.

Если выбрать endpoint из списка на основной странице или на странице поиска, отобразится описание запроса с параметрами и коды ответа.

Чтобы отправить запрос в приложение, нужно нажать Test Request.

Слева на странице можно посмотреть и изменить параметры запроса, заголовки и куки. В поле Code Snippet формируется код запроса с актуальными параметрами. По дефолту выбрана системная программа Curl, но в выпадающем списке спрятано много языков программирования — в том числе C#.

Send отправляет запрос, а справа отображается ответ. В целом вся эта страница по функционалу напоминает Postman.

Конфигурация Scalar

Сильная сторона Scalar — это количество возможных настроек. Изменить можно тему, переключатели темного режима и многое другое.

app.MapScalarApiReference(options =>
{
    options
    .WithTheme(ScalarTheme.Kepler)
    .WithDarkModeToggle(true)
    .WithClientButton(true);
});

Про темы. Сейчас много готовых тем, но если хочется, можно полностью изменить внешний вид страницы, используя CSS. Прочитать

Про работу с аутентификацией. Scalar поддерживает различные схемы аутентификации, включая API Key, OAuth2 и HTTP Basic/Bearer. Это позволяет предустанавливать определённые данные аутентификации. Пример настройки аутентификации OAuth2:

app.MapScalarApiReference(options => options
    .AddPreferredSecuritySchemes("OAuth2")
    .AddOAuth2Authentication("OAuth2", scheme => 
    {
        scheme.Flows = new ScalarFlows
        {
            AuthorizationCode = new AuthorizationCodeFlow
            {
                ClientId = "your-client-id",
                RedirectUri = "https://your-app.com/callback"
            },
            ClientCredentials = new ClientCredentialsFlow
            {
                ClientId = "your-client-id",
                ClientSecret = "your-client-secret"
            }
        };
        
        scheme.DefaultScopes = ["profile", "email"];
    })
);

Полная информация о подключении различных типов аутентификации и о настройке Scalar в целом — в официальной документации.

Итог

Мне Scalar понравился. Из плюсов — простое подключение и начало работы, гибкая настройка, хорошая документация с примерами. Ещё большой плюс — активное развитие кодовой базы. По функционалу Scalar сильно выигрывает у SwaggerUI.

Из минусов отмечу непривычный после Swagger-а интерфейс, который скорее напоминает Postman на минималках. И уверен, что все имеющиеся функции нужны далеко не в каждом проекте.