В .Net больше нет Swashbuckle. То есть из коробки больше нет Swagger UI чтобы тестировать свеженаписанные API.
Microsoft поддерживают собственный пакет Microsoft.AspNetCore.OpenApi для генерации OpenAPI спецификации из кода (Code First подход), а для тестирования предлагают использовать .http файлы и Endpoints Explorer встроенный в Visual Studio. Postman и NSwag всё ещё с нами, не говоря о том что можно и сам Swashbuckle установить, только перспективы его поддержки весьма туманны.
Активно развивающейся альтернативой Swagger UI является Scalar, который можно удобно интегрировать с .Net и ещё дюжиной популярных стеков.
Хочу писать Code First и просто заменить Swashbuckle
Для тех кто по старинке пишет свои сервисы Code First, Scalar является drop-in заменой. Достаточно установить пакет и заменить
app.UseSwaggerUI(...);На
app.UseScalarApiReference();После запуска сервиса UI готов к использованию и доступен по адресу http://localhost:{ваш порт}/scalar/
У меня есть OpenAPI документ, хочу запустить UI с ним
Я придерживаюсь Design API First подхода в разработке, и сперва получаю OpenAPI документ используя TypeSpec – недавно вышедший в релиз удобный инструмент с хорошей поддержкой и исчерпывающей документацией, если интересно могу написать про его применение отдельно. Итого 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/
Спасибо за внимание, надеюсь статья была вам полезной!