12.05.2021 16:06
MaxRokatansky 2 2400 Источник

Перевод подготовлен в рамках набора студентов на курс «C# ASP.NET Core разработчик».

Всех желающих приглашаем на двухдневный онлайн-интенсив «Serverless на базе azure». День 1: обзор облачных сервисов, что такое serverless computing, serverless computing на базе azure сервисов, создание azure function. День 2: выбор базы, добавление azure storage, добавление безопасности, ARM шаблоны.

Мы продолжаем серию статей о создании HTTP API с помощью .NET 5. В предыдущей статье мы рассмотрели создание обнаруживаемых HTTP API с помощью ASP.NET Core 5 Web API. В этой статье мы рассмотрим пакеты и инструменты для работы с HTTP API с открытым исходным кодом. Ну что ж, приступим!

  • Опенсорсные инструменты и пакеты для работы с HTTP API (эта статья)

Опенсорсные инструменты, пакеты и расширения для разработки HTTP API 

Эта статья охватывает ряд вещей, которые любой .NET-разработчик, планирующий работать над HTTP API, мог бы захотеть включить в свой набор инструментов или список зависимостей. Мы покажем вам несколько новых интересных фреймворков, которые созданы на основе ASP.NET Core Web API и, надеюсь, упростят создание и тестирование HTTP API на .NET. Существует так много возможностей в виде пакетов NuGet, расширений Visual Studio и Visual Studio Code, а также независимо поддерживаемых фреймворков, что мы не можем охватить их все в одной статье. Так что не стесняйтесь делиться в комментариях вашими любимыми инструментами и пакетами для Web API.

NuGet-пакеты для создания .NET HTTP API

В первой части этой статьи мы рассмотрим некоторые из наиболее важных NuGet-пакетов в вашем наборе инструментальных средств для HTTP API. Многие из этих инструментов используются в наших собственных личных проектах и ??инструментальных пакетах. Некоторые из этих инструментов можно найти в наших шаблонах, программных средствах и зависимостях.

Генерация OpenAPI

В первой статье этой серии мы затронули идею создания доступных для обнаружения API. Поскольку термин «обнаруживаемые» (discoverable) в терминах API связан с обнаружением служб, возможно, более подходящий термин для этой статьи был бы «хорошо описанные» (well-described). Описывая API с использованием спецификации OpenAPI (ранее называвшейся Swagger), разработчики получают разнообразные возможности генерации кода и интеграции. Мы еще вернемся к этой теме позже в этой серии. Дело в том, что генерация OpenAPI важна и должна быть чем-то, что вы, по крайней мере, обязательно генерируете, если не полноценно проектируете.

Конечно, некоторые считают идею генерации спецификаций OpenAPI на основе кода подходом «шиворот-навыворот» (инструменты проектирования — это тема, которую мы затронем позже). Но при быстрой разработке или для поддержании хорошего уровня «спроектированности», и при этом используя генерацию спецификации из кода, у вас есть два основных варианта для Web API традиционного ASP.NET и ASP.NET Core: NSwag и Swashbuckle. Оба этих проекта почти полностью поддерживаются мейнтейнерами в одиночку (с небольшими группами контрибьюторов-энтузиастов), и оба оказали значительное влияние на экосистему HTTP API .NET.

NSwag

Хотя наиболее популярным сценарием использования NSwag является генерация спецификации OpenAPI из проектов Web API контроллеров с помощью NSwag.AspNetCore, команда проекта внесла целый ряд других контрибьютов:

  • Десктопное приложение NSwagStudio, которое позволяет использовать большинство функций NSwag без написания кода.

Богатая экосистема NuGet-пакетов NSwag используется функцией Visual Studio Connected Services «OpenAPI SDK Generation», которую мы рассмотрим более подробно в третьей статье этой серии. Инструменты генерации кода NSwag создают качественный идиоматический клиентский C# код для хорошо описанных API.

Swashbuckle

Swashbuckle используется в миллионах Web API проектов, созданных клиентами и штатными командами. Он также был принят командой Swagger Codegen в своих шаблонах, которые используются во многих API продуктах экосистемы. Учитывая степень присутствия Swashbuckle в сфере Web API, он используется в наших шаблонах с момента релиза .NET 5 RC. Он подключен по умолчанию, но может быть отключен в диалоговом окне нового проекта в Visual Studio (или с помощью параметра --no-openapi в .NET CLI команде dotnet new webapi).

Swashbuckle также имеет .NET CLI инструмент Swashbuckle.CLI, который можно использовать для генерации спецификаций OpenAPI во время MSBuild или dotnet publish команд. В примере проекта есть пример файла проекта C#, показывающий, как использовать интерфейс командной строки Swashbuckle в процессе сборки.

Microsoft.OpenAPI

Ни один список значимых NuGet-пакетов для экосистемы разработчиков HTTP API не был бы полным без Microsoft.OpenAPI. Являясь неотъемлемой зависимостью большинства поддерживающих OpenAPI проектов в сообществе .NET и Azure, этот пакет дает целый набор возможностей:

  • Трансляция между версиями Swagger и OpenAPI, YAML или различными формами JSON.

  • Предоставляет модель единого общего объекта в .NET для описаний OpenAPI.

  • Чтение и написание описаний OpenAPI.

Если вы создаете приложение или NuGet-пакет для разработчиков HTTP API .NET с помощью OpenAPI, вы, вероятно, захотите взглянуть на Microsoft.OpenAPI. Он значительно облегчает задачу парсинга или написания документов и описаний OpenAPI.

ASP.NET API Versioning

Одна из наиболее важных вещей при создании API, о которой вам никто не расскажет, пока не станет станет слишком поздно, заключается в том, что в какой-то момент вам нужно будет зарелизить критические изменения в API, используемые многими вашими клиентами. Управление версиями API сложно, но еще сложнее, когда вам приходится делать все вручную, поэтому наличие такого инструмента как ASP.NET API Versioning (используемого огромным количеством клиентов и штатных команд) - это просто фантастика. Скотт Хансельман писал об API Versioning еще в 2016 году, и с тех пор оно стало очень важным активом в разработке Web API.

API Versioning позволяет декорировать API контроллеры дополнительными атрибутами, которые включают версии API, в которых должны отображаться операции контроллера.

[ApiVersion("1.0")]
[ApiVersion("1.1")]
public class ShopController : ControllerBase
{
}

Экшн-методы контроллера также могут быть декорированы, чтобы идентифицировать версии, в которых они отображаются или «появляются». В примерах кода, дополняющих эту серию, вы увидите методы GetProducts и GetProductsPage, добавленные в API версии 1.1.

[HttpGet("/products", Name = nameof(GetProducts))]
public async Task<ActionResult<IEnumerable<Product>>> GetProducts()
{
    return await Task.FromResult(Ok(StoreServices.GetProducts()));
}

[HttpGet("/products/page/{page}", Name = nameof(GetProductsPage))]
[MapToApiVersion("1.1")]
public async Task<ActionResult<IEnumerable<Product>>> GetProductsPage([FromRoute] int page = 0)
{
    var pageSize = 5;
    var productsPage = StoreServices.GetProducts().Skip(page * pageSize).Take(pageSize);
    return await Task.FromResult(Ok(productsPage));
}

Для API Versioning существует множество примеров и статей в Wiki о том, как начать работу. Одна из них показывает, как использовать вместе API Versioning и Swashbuckle, откуда я позаимствовал пример проекта, сопровождающий эту серию статей. Добавив немного дополнительного кода в Startup.cs и используя несколько инфраструктурных классов для итерации по различным версиям API в вашем проекте, вы сможете задействовать API Versioning, чтобы помочь вам создать отдельные независимые страницы пользовательского интерфейса Swagger для нескольких версий ваших API. Это изменяет пользовательский интерфейс Swagger, чтобы отобразить раскрывающееся меню, содержащее версии API в вашем проекте.

Обратите внимание на операции в Shop - их 3 в API версии 1.0. Но как только мы изменим версию в меню на 1.1, появится новая операция GetProductsPage, доступная только в версии API 1.1.

Инструменты генерации кода в Visual Studio Connected Services OpenAPI SDK знают о строке запроса api-version, которую теперь ожидает API. При использовании API Versioning сгенерированный код также добавляет параметр для захвата строки версии API. Это можно сделать по умолчанию, чтобы API Versioning автоматически выбирало предполагаемую версию, но в этом случае я подразумеваю более занудный подход к моему клиенту.

// create a product
apiClient.CreateProductAsync("1.1", 
  new CreateProductRequest
  {
      Id = 1000,
      InventoryCount = 0,
      Name = "Mild Salsa"
  });

// update a product's inventory
apiClient.UpdateProductInventoryAsync(1000, "1.1", 
  new InventoryUpdateRequest
  {
      CountToAdd = 50,
      ProductId = 1000
  });

Refit

Refit - это автоматическая типобезопасная REST библиотека для .NET. Она превращает ваш интерфейс в лайв REST-клиент. Рассмотрим приведенный ниже пример интерфейса IContosoOnlineOrdersApiClient, который будет предоставлять сигнатуры методов для вызова некоторых методов API.

public interface IContosoOnlineOrdersApiClient
{
    [Get("/products")]
    Task<IEnumerable<Product>> GetProducts();

    [Post("/products")]
    Task CreateProduct([Body] CreateProductRequest request);
}

Класс RefitRestService генерирует реализацию IContosoOnlineOrdersApiClient, которая заставляет HttpClient делать его вызовы. В примере солюшена есть проект клиента Refit, демонстрирующий, как использовать клиент Refit для доступа к внутреннему HTTP API.

var client = RestService.For<IContosoOnlineOrdersApiClient>("http://localhost:5000");
var products = await client.GetProducts();
await client.CreateProduct(new CreateProductRequest
{
  Id = 1001,
  InventoryCount = 10,
  Name = "Taco Shells"
});
products = await client.GetProducts();

Если вы вручную создаете собственный клиентский код для серверных API, Refit - отличный вариант, на который вам следует обратить внимание. Refit обеспечивает упрощенный подход к созданию клиентов для HTTP API и абстрагирует всю тонкую HttpClient семантику.

Инструменты и расширения для разработки и тестирования HTTP API

Помимо этих полезных NuGet-пакетов, есть несколько отличных инструментов, которые вы можете использовать как из командной строки, так и в ваших любимых IDE для проектирования, создания и тестирования HTTP API.

The HttpRepl

HttpRepl является .NET CLI Global инструментом, который может предоставить способ просмотра HTTP API, описанных спецификациями OpenAPI, в стиле каталогов стиля исследует. После установки вы можете использовать команду httprepl -o <openapi-url>, чтобы подключиться к любому проекту Web API, описанному OpenAPI, и перемещаться по нему с помощью знакомых команд, таких как ls или dir, и навигации по структуре API как в дереве каталогов.

Если вы еще не пробовали HttpRepl, ознакомьтесь с документацией HttpRepl для получения дополнительной информации о различных командах, которые он предлагает. В документации также показано, как вы можете настроить HttpRepl в качестве «браузера», чтобы вы могли «F5-дебажить в HttpRepl», если вам удобнее работать с терминалом.

REST Client для Visual Studio Code

Есть несколько впечатляющих инструментов HTTP API, которые поставляются как расширения для Visual Studio Code. Один из них, REST Client, предлагает тестирование запросов HTTP API в среде IDE. Создавая файлы .http, в которые вы пишете свои собственные тесты запросов, вы можете запустить REST Client для активации «Send Request» ссылок над каждым HTTP-запросом, который вы собираетесь тестировать.

Network Console

Microsoft Edge DevTools недавно включила экспериментальную функцию под названием Network Console. Network Console предлагает пользователям Edge функционал тестирования HTTP API в браузере. Чтобы опробовать ее, вам сначала нужно включить Network Console в экспериментальных функциях Edge DevTools.

После подключения Network Console вы можете кликнуть правой кнопкой мыши любой ранее сделанный HTTP-запрос и выбрать пункт меню «Edit and Resend».

Клик по «Edit and Resend» откроет инструмент тестирования HTTP API прямо внутри Edge. Т.е. когда вы создаете веб-приложения, которые исполняют обратные HTTP API вызовы на сервер, или когда вы создаете приложения Blazor, которые делают подобные вещи, вы можете повторно отправлять сообщения и анализировать поведение API, не покидая браузер.

OpenAPI Editor

Редактирование или создание документов OpenAPI вручную может быть сложной задачей, поэтому вам может пригодиться отличный редактор и расширение для проектирования OpenAPI прямо в Visual Studio Code. OpenAPI Editor предоставляет именно такую ??функциональность. Это расширение включает в себя такие функции, как:

  • Пользовательский интерфейс Swagger UI и превью ReDoc 

  • IntelliSense, когда вы вручную редактируете содержимое JSON/YAML для своей спецификации OpenAPI.

  • Навигация в виде окон инструментов внутри Visual Studio Code.

Я могу использовать окно инструментов, чтобы найти отдельную операцию в моем HTTP API, вместо того, чтобы прокручивать огромный файл JSON.

Фреймворки, созданные поверх ASP.NET Core или Web API

В таком активном сообществе для сторонников открытого исходного кода не редкость расширять платформу ASP.NET своими собственными изобретениями или даже развивать Web API в новых интересных направлениях. Два недавних проекта - отличные примеры того, как сообщество развивает ASP.NET и Web API в новых направлениях.

API Endpoints

Стив Смит начал работу над захватывающим проектом, известным как API Endpoints, который строится поверх Web API ASP.NET Core. Задача проекта состоит в том, чтобы отвлечь разработчика от необходимости думать о концепции контроллера для создания своего HTTP API. Стив написал о API Endpoints в своем блоге, описав свои стремления и направление проекта. По сути, API Endpoints абстрагируют контроллер, поэтому у вас остается немного меньше работы с кодом, при этом вы по-прежнему можете использовать полный набор функций, предоставляемый классами MVC Action Result ASP.NET Core.

[HttpPost("/authors")]
[SwaggerOperation(
    Summary = "Creates a new Author",
    Description = "Creates a new Author",
    OperationId = "Author.Create",
    Tags = new[] { "AuthorEndpoint" })
]
public override async Task<ActionResult<CreateAuthorResult>> HandleAsync([FromBody]CreateAuthorCommand request)
{
    var author = new Author();
    _mapper.Map(request, author);
    await _repository.AddAsync(author);

    var result = _mapper.Map<CreateAuthorResult>(author);
    return Ok(result);
}

Поскольку API Endpoint построен поверх Web API, вы можете использовать Swashbuckle, NSwag или любое другое расширение Web API вместе с API Endpoints и использовать преимуществами более широкого стека Web API, но с более модульным подходом, нежели подход, основанный на MVC.

Carter Project

Carter project от Carter Community привносит еще большую модульность в ваши приложения ASP.NET Core. Вдохновленный Nancy project, Carter предлагает ориентированный на эндпоинты подход к созданию HTTP API с помощью ASP.NET Core. Синтаксис Carter отлично подходит для разработчиков, которые ценят подход маршрутизации эндпоинтов, и предлагает чистый набор API для быстрого начала работы.

public class HomeModule : CarterModule
{
    public HomeModule()
    {
        Get("/", async (req, res) => await res.WriteAsync("Hello from Carter!"));
    }
}

Благодаря многочисленным примерам и документации проект легко изучать и экспериментировать с ним, а также он предлагает интересный подход к созданию HTTP приложений. OpenAPI встроен в Carter по умолчанию, поэтому создаваемые вами эндпоинты могут автоматически выводиться в спецификации OpenAPI. Carter также может быть объединен с традиционным Web API и структурой приложения ASP.NET Core, поэтому вы можете использовать Carter вместе со знакомым middleware и службами ASP.NET Core.

Заключение

API предназначены для того, чтобы наши приложения были более открытыми для изменений и взаимодействия с другими API, приложениями и службами. Существует множество инструментов, служб и платформ с открытым исходным кодом и даже больше сторонних предложений, созданных на основе Web API ASP.NET и ASP.NET Core, чтобы предоставить вам безграничные возможности для расширения. Пакеты и инструменты, перечисленные в этом посте, - это лишь некоторые из тех, что мы используем в наших собственных проектах и ??экспериментах, в то время как другие обозначают новые направления в ASP.NET и подход нашего сообщества к созданию программного обеспечения.

Мы надеемся, что эта и другие статьи в этой серии вдохновят вас и принесут вам приятный опыт разработки API. Пожалуйста, поделитесь в комментариях другими инструментами, расширениями или пакетами, которые, по вашему мнению, могут дополнить эту статью.

Узнать подробнее о курсе «C# ASP.NET Core разработчик».

Участвовать в двухдневном онлайн-интенсиве «Serverless на базе azure».