Когда речь идет о точном описаниии программного интерфейса, в особенности его данных, проще и эффективнее использовать структурированный инструмент, такой как формат описания API. Будучи похожим на код и стандартизированным описанием API, он предлагает множество преимуществ:

  • значительно упрощает обмен вашим дизайном с любым, кто участвует в вашем проекте
  • его легко могут понять все, кто знает этот формат и инструменты документирования API

Спецификация OpenAPI (OAS) - это формат описания REST API, не зависящий от языка программирования. Этот формат продвигается OpenAPI Initiative (OAI), которая “…создана консорциумом перспективных отраслевых экспертов, осознающих огромную ценность стандартизации описания REST API. Являясь открытой структурой управления в рамках Linux Foundation, OAI нацелена на создание, развитие и продвижение независимого от поставщика формата описания”. OAS (https://openapis.org) - это формат сообщества; каждый может внести свой вклад через репозиторий на Github .

OpenAPI в сравнении с Swagger

Раннее известный как спецификация Swagger, этот формат был передан OAI в ноябре 2015 года и переименован в спецификацию OpenAPI в январе 2016 года. Последней версией (2.0) спецификации Swagger стала OpenAPI 2.0. Она развивалась и на момент написания этой статьи ее последняя версия - 3.0.

Изначально спецификация Swagger была создана Тони Тэмом для облегчения автоматизации документирования API и генерации набора средств разработки (Software Development Kit) при работе надо продуктами Wordnik . Эта спецификация была лишь чатью фреймворка под названием Swagger API, включавшего в себя такие инструменты, как аннотация кода, генератор кода и пользовательский интерфейс документирования. Все они использовали преимущества спецификации Swagger. Бренд Swagger по-прежнему существует и предоставляет инструменты API с использованием OAS, но имейте в виду, что при поиске информации об этом формате вы можете столкнуться с обоими именами.

Зачем использовать формат описания API?

В самом деле, вы могли бы описать программный интерфейс, используя текстовый процессор или электронную таблицу. Вы также можете легко поделится этим документом с другими. Но способны ли вы с легкостью управлять его версиями? Можно ли создать из него документацию? Или сгенерировать код? Можете ли вы настроить с его помощью иструменты, связанные с API? Можете ли вы… ? Наверное, я мог бы написать целую страницу подобных вопросов. Использование формата описания API имеет преимущество на протяжении всего жизненого цикла API, особенно на этапе проектирования. Это выгодно не только поставщикам API, но и его потребителям.

Эффективаное описание API сродни написанию кода

Документ OAS - это простой текстовый файл, который легко можно сохранить в системе управления версиями, такой как Git, как и код. Таким образом, управлять версиями и отслеживать изменения будет просто.

Документ OAS имеет структуру, которая помогает более эффективно описывать программный интерфейс. Вы должны описать ресурсы, операции, параметры и ответы. Вы можете определить повторно используемые компоненты (например, модель данных), избегая и рискованного искусства копирования и вставки фрагментов описания API.

Легкий обмен описаниями API и документирование API

Документом OAS можно легко поделиться с другими даже за пределами вашей команды или компании, чтобы получить отзыв о своем дизайне. В отличие от определенного внутренниго формата, известного лишь немногим, формат OAS очень распространен. Люди могут импортировать документ в онлайн-редактор Swagger Editor или множество других инструментов API. В качестве альтернативы, чтобы не мешать никому самим документом OAS, вы можете предоставить доступ к готовой к использованию и удобной для восприятия визуализации. Документ OAS можно использовать для создания справочной документации по API, в которой показаны все доступные ресурсы и операции. Для этого можно использовать пользовательский интерфейс Swagger , который показывает документ OAS как в правой панели редактора Swagger Editor.

Есть и другие инструменты. Например, в качестве альтернативы Swagger UI вы можете использовать такой инструмент, как ReDoc , также с открытым исходным кодом.

Генерация код и не только

Как только API будет описан с помощью формата описания API, из него можно частично сгенерировать код реализации. Вы получаете пустой костяк исходного кода, который также можно использовать для создания рабочего макета. Потребители также могут воспользоваться преимуществами таких машиночитаемых описания API для генерации кода для использования API. И такой формат также может использоваться инструментами тестирования API или безопасности, а также многими другими инструментами, связанными с API. Например, большинство решений для API-шлюзов (прокси, созданные для предоставления доступа и защите API) можно настроить с помощью файла описания API, такого как документ OAS.