Что такое спецификация OpenAPI?

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

Вот почему следует рассмотреть вопрос о наличии спецификации OpenAPI для API:

• Документируйте API стандартизированным способом. Документируйте спецификацию API в согласованном и удобочитаемом формате.
• Создайте клиентский пакет SDK. Используйте такие средства, как Kiota , чтобы автоматизировать создание клиентских библиотек на различных языках программирования.
• Создание макетного API. Создайте макет серверов на основе спецификации API, которая помогает во время ранних этапов разработки, когда фактический API еще не реализован.
• Улучшение совместной работы. Предоставьте различным командам (интерфейсной части, серверной части, обеспечения качества) четкое понимание возможностей и ограничений API, что помогает новым участникам команды быстро войти в курс дела.
• Упрощение тестирования и проверки. Автоматизация проверки запросов и ответов API в спецификации, что упрощает выявление несоответствий.
• Интеграция с средствами управления API. Легко интегрируйте, развертывайте и отслеживайте API с множеством средств управления API и шлюзов, таких как Центр API Azure и Azure Управление API.
• Упрощение конфигурации шлюза API. Используйте спецификации OpenAPI для настройки шлюзов API и автоматизации таких задач, как маршрутизация, преобразования и параметры общего доступа к ресурсам между источниками.

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

У вас еще нет спецификации OpenAPI?

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

Approach	Что вы получаете	На что обратить внимание
Напишите от руки	Полный контроль над описаниями и примерами	Требуется время, и это отклоняется от реального API
Создайте это из аннотаций кода	Спецификация, которая синхронизируется с кодом	Вам нужен доступ к коду API, и фреймворк должен поддерживать его.
Создайте его из записанного трафика	Спецификация для любого API, который можно вызвать, включая те, которые вам не принадлежат	Он охватывает только записанные запросы, поэтому используйте нужные вам части API

Dev Proxy записывает запросы и ответы между приложением и API и создает из них спецификацию OpenAPI. Инструкции см. в разделе Создание спецификации OpenAPI.

Следующий шаг

Создание спецификации OpenAPI