Scalar на замену Swashbuckle в .NET 9 и как это готовить с Design API First

В .Net больше нет Swashbuckle ^[1]. То есть из коробки больше нет Swagger UI чтобы тестировать свеженаписанные API.

Microsoft поддерживают собственный пакет Microsoft.AspNetCore.OpenApi для генерации OpenAPI спецификации из кода (Code First подход), а для тестирования предлагают использовать .http файлы и Endpoints Explorer встроенный в Visual Studio. Postman и NSwag всё ещё с нами, не говоря о том что можно и сам Swashbuckle установить, только перспективы его поддержки весьма туманны.

Активно развивающейся альтернативой Swagger UI является Scalar ^[2], который можно удобно интегрировать с .Net и ещё дюжиной популярных стеков.

Хочу писать Code First и просто заменить Swashbuckle

Для тех кто по старинке пишет свои сервисы Code First, Scalar является drop-in заменой. Достаточно установить пакет и заменить

app.UseSwaggerUI(...);

На

app.UseScalarApiReference();

После запуска сервиса UI готов к использованию и доступен по адресу http://localhost:{ваш порт}/scalar/

У меня есть OpenAPI документ, хочу запустить UI с ним

Я придерживаюсь Design API First подхода в разработке, и сперва получаю OpenAPI документ используя TypeSpec ^[3] – недавно вышедший в релиз удобный инструмент с хорошей поддержкой и исчерпывающей документацией, если интересно могу написать про его применение отдельно. Итого openapi.json у меня есть, осталось его захостить и получить а-ля Swagger UI страницу где можно смотреть примеры и дёргать эндпоинты.

Сделать это тоже очень просто. Достаточно включить статические файлы, и зарегистрировать Scalar в приложении. Я положил openapi.json по кастомному пути, поэтому указал путь до него в параметре:

// Program.cs

// Это вся необходимая конфигурация

app.UseStaticFiles();

if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference(options =>
    {
        options.WithOpenApiRoutePattern("/openapi-typespec/openapi.json");
    });
}

Сам файл я получил предварительно в виде json (можно сконвертировать из openapi.yaml ) и положил по пути {ваш сервис}/wwwroot/openapi-typespec/openapi.json .

После запуска сервиса UI готов к использованию и доступен по адресу http://localhost:{ваш порт}/scalar/

Спасибо за внимание, надеюсь статья была вам полезной!