Перед вами карта компетенций системного аналитика и сегодня мы поговорим про open API.
Open API
Open API это по сути спецификация для описания REST API, о котором мы говорили в предыдущей статье. Клиент работает с вашими серверами и сервисами (облачными или не очень) отправляя запросы и получая ответы в соответствии с определенным API. Чтобы разобраться с вашим API было проще, необходимо описать его в какой-то понятной всем нотации. Да и обновления такого описания желательно сделать автоматическими. Для этого и существует open API.
Спецификация open API
Спецификация open API может автоматически генерироваться прямо из кода и содержит следующие элементы. Paths – это адреса для сообщений REST API (как вы помните, для каждого сообщения должен быть определен свой адрес). Parameters описывает состав атрибутов запроса и требований к ним (к их содержанию и типу данных). В Responses описаны все возможные ответы на запрос.
Swagger UI
С помощью swagger UI спецификацию open API можно «оживить». Тут опять же автоматически, но не на основе кода, а на основе спецификации создается простенький UI, в котором доступны как описание спецификации, так и возможность протестировать API при помощи реальных запросов. Прямо в этом UI вы сможете создавать и редактировать запросы в нужной для API структуре и получать ответы на такие запросы. Как правило для того чтобы отправить запрос, необходимо авторизоваться в системе и получить авторизационный токен. Начинать тестирование всегда нужно с выяснения того как получить авторизационные данные и, собственно, с получения этих данных.
Заключение
В заключении повторим основные моменты:
- Если вы решили использовать REST API в вашем приложении, вам необходимо сделать удобную и понятную документацию.
- Open API позволит сгенерировать такую документацию прямо из кода.
- А swagger UI станет отличным полигоном, на котором клиенты смогут протестировать ваше API.