Инструменты и для Создания .NET HTTP API. Начало
В этой серии постов опишу набор инструментов для создания полноценных приложений HTTP API в .NET.
Начнём с наиболее распространённых NuGet пакетов.
OpenAPI
Хорошо спроектированный API должен быть «обнаруживаемым». То есть службы, представленные в API должны быть легко доступны. Возможно, правильнее будет назвать такие API хорошо описанными. Описывая API с использованием спецификации OpenAPI (ранее называвшейся Swagger), разработчики открывают для себя различные возможности генерации кода и интеграции. Для создания и поддержки автоматически сгенерированной спецификации API на основе кода у вас есть два основных варианта: NSwag и Swashbuckle. Оба этих проекта почти полностью поддерживаются отдельными людьми с небольшими группами контрибуторов, и оба оказали значительное влияние на экосистему .NET HTTP API.
NSwag
Наиболее популярным сценарием использования NSwag является создание спецификации OpenAPI из проектов WebAPI-контроллеров с помощью пакета NSwag.AspNetCore. Однако NSwag предлагает целый ряд других функций:
- Генерация кода строго типизированных клиентов HTTP API на C#, кода WebAPI-контроллеров из OpenAPI и кода клиентов на TypeScript.
- Создание спецификации OpenAPI из существующих сборок .NET (из двоичных файлов, а не исходного кода).
- Настольное приложение NSwagStudio, которое позволяет использовать большинство функций NSwag без написания кода.
Swashbuckle
Swashbuckle использовался миллионами проектов веб-API и также используется в шаблонах .NET с выпуска .NET 5 RC. Он включен по умолчанию, но может быть выключен в диалоговом окне нового проекта в Visual Studio (или с помощью параметра
--no-openapi в команде dotnet new webapi).Swashbuckle также имеет инструмент командной строки
Swashbuckle.CLI, который можно использовать для генерации спецификаций OpenAPI во время публикации в MSBuild или dotnet publish.Microsoft.OpenAPI
Microsoft.OpenAPI включён в большинство проектов, поддерживающих OpenAPI, в сообществе .NET и Azure и отвечает за различные функции:
- Переход между версиями Swagger и OpenAPI, YAML или JSON.
- Предоставление единой общей объектной модели в .NET для описаний OpenAPI.
- Чтение и запись описаний OpenAPI.
Если вы создаёте приложение или пакет NuGet для разработчиков .NET HTTP API с помощью OpenAPI, попробуйте использовать пакет Microsoft.OpenAPI. Это значительно облегчит задачу синтаксического анализа или написания документов и описаний OpenAPI.
API Versioning
При работе с WebAPI рано или поздно вам придётся столкнуться с необходимостью внесения критических (breaking) изменений. Тогда на помощь придёт пакет API Versioning. Он позволяет декорировать API контроллеры атрибутами, указывающими, в каких версиях API какие контроллеры или методы должны появляться.
Пример совместного использования API Versioning и Swashbuckle.
Refit
Refit позволяет легко создавать REST клиентов для существующих API. Он предоставляет упрощённый способ создания HTTP клиентов, абстрагируясь от всех нюансов семантики
HttpClient.Продолжение следует…
Источник: https://devblogs.microsoft.com/aspnet/open-source-http-api-packages-and-tools/