Документирование веб-API ASP.NET Core с помощью инструментов Swagger

  • 5 мин

API может иметь большое значение, но он не может получить тяги, если разработчики не знают, как его использовать. Разработчики хотят быстро выполнить интеграцию API. Хорошо подготовленная документация API позволяет разработчикам определить его возможности и как их следует использовать. Это делает интеграцию более аффективной.

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

Общие сведения об OpenAPI.

OpenAPI является спецификацией, используемой для описания REST API. Это не зависит от языка и позволяет описать весь API, включая:

  • доступные конечные точки;
  • параметры операции;
  • методы проверки подлинности;
  • контактные сведения и другую информацию.

Для написания спецификаций API можно использовать YAML или JSON. Люди и компьютеры могут использовать спецификацию OpenAPI, чтобы разобраться в возможностях API без необходимости получать доступ к исходный коду.

Что такое Swagger?

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

Например, Swagger UI (пользовательский интерфейс Swagger) является инструментом, который используется для визуального отображения в браузере документации API, которая была определена с помощью спецификации OpenAPI. Swagger Codegen может использовать те же спецификации, что и OpenAPI, и создавать клиентские пакеты SDK.

Что такое Swashbuckle?

Swashbuckle является реализацией Swagger с открытым кодом, которая используется для создания документации Swagger для API .NET Core с использованием отражения .NET.

Swashbuckle состоит из трех ключевых компонентов.

  • Swashbuckle.AspNetCore.Swagger: этот компонент является как объектной моделью Swagger, так и промежуточным слоем для предоставления объектов SwaggerDocument, например, конечных точек JSON.

  • Swashbuckle.AspNetCore.SwaggerGen: эта библиотека является генератором Swagger, который напрямую создает объекты SwaggerDocument из путей, контроллеров и моделей. Библиотека обычно объединяется с ПО промежуточного слоя конечной точки Swagger для автоматического предоставления JSON Swagger.

  • Swashbuckle.AspNetCore.SwaggerUI: этот пакет является встроенной версией средства пользовательского интерфейса Swagger. Он обрабатывает JSON-файл Swagger, чтобы создать многофункциональный настраиваемый интерфейс, который используется для описания функций веб-API. К нему можно отнести встроенное окружение теста, используемое в открытых методах.

  • Swashbuckle CLI: после установки это глобальное средство .NET позволяет создавать спецификации OpenAPI во время сборки и публикации. Ссылка для скачивания CLI Swashbuckle расположена в конце этого модуля.

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