openapi.json OpenAPI 3.0.0, 15 методов
Интерактивная версия — та же спецификация в Redoc: методы, схемы и примеры ответов в одном окне, без установки чего-либо.
Как это устроено#
Спецификация не пишется руками. Она собирается прогоном тех же тестов, которые проверяют поведение API: каждый пример запроса и ответа в ней это реальный ответ работающего кода. Поэтому расхождение между спецификацией и поведением означало бы падающий тест, а не устаревшую документацию.
Обратная сторона: спецификация описывает формы запросов и ответов, но не объясняет смысл. За тем, почему товарооборот отличается от выручки и почему лимит считается по торговому центру, стоит идти в разделы этого сайта.
Что с ней делать#
Сгенерировать клиент. Любой генератор по OpenAPI 3.0 — openapi-generator,
oapi-codegen, NSwag — соберёт типизированный клиент под нужный язык.
npx @openapitools/openapi-generator-cli generate \
-i openapi.json -g python -o ./rentu-clientИмпортировать в Postman. Для Postman есть готовая коллекция с переменными, автоматическим сохранением токена и подписями параметров, она удобнее прямого импорта спецификации: Готовые клиенты.
Посмотреть в браузере. Спецификацию можно открыть в любом просмотрщике OpenAPI, например в Swagger Editor или Redoc.
Что учесть#
Спецификация описывает контракт, но не описывает поведение, зависящее от состояния:
- какие методы доступны — определяется тарифом центра;
- какие центры видны — определяется ролями владельца ключа;
- какие поля придут в месячном отчёте — зависит от тарифа.
Сгенерированный клиент будет содержать все методы. Это не значит, что все они
ответят 200.