OpenAPI Specification

OpenAPI Specification (ранее Swagger) — это стандартный машиночитаемый формат (на YAML или JSON) для описания REST API: его эндпоинтов, параметров, форматов запросов и ответов, аутентификации и кодов ошибок. Один файл `openapi.yaml` становится единым источником истины о том, что делает API. Его настоящая сила — в инструментах. Из одной спецификации можно автоматически сгенерировать интерактивную документацию, типизированные клиентские SDK на десятке языков, серверные заготовки, мок-серверы и контрактные тесты — так что документация, клиент и сервер никогда не расходятся. Для SaaS-разработчиков это важно в двух направлениях. Когда вы публикуете API, наличие OpenAPI-спецификации резко упрощает интеграцию вашего продукта: клиенты могут сгенерировать клиент вместо ручного написания запросов. Когда вы подключаете чужой API, хорошая спецификация — сильный сигнал качества интеграции и экономит дни догадок. На ней держатся экосистемы вроде Postman, и она питает функции импорта API в большинстве iPaaS-платформ.