ИИ-инструменты и скрипты
API Change Report: что может сломаться у потребителей вашего API, по двум спецификациям
Для команд API и агентств: скрипт сравнивает ваш старый и новый файл OpenAPI или Swagger по фиксированным правилам, а агент составляет отчёт о потенциально ломающих изменениях, руководство по миграции, запись для журнала изменений и уведомление для интеграторов, которые вы проверяете. Отчёт о том, что может сломаться у потребителей API между двумя версиями.
Что вы получите: 1 файл · 76.62 KB · ZIP
Варианты покупкиОписание товара
Описание
Для бэкенд-разработчиков, команд API и агентств, которые выпускают новую версию HTTP API и должны сообщить тем, кто его вызывает, что изменилось.
Передайте своему агенту старое и новое описание вашего API (OpenAPI 3.x или Swagger 2.0, JSON или YAML). Агент составит отчёт об изменениях, руководство по миграции и уведомление для интеграторов, которые вы проверите до публикации.
Отчёт перечисляет потенциально ломающие изменения, найденные при сравнении двух файлов. Это отправная точка для проверки вашей командой, а не подтверждённая оценка совместимости.
Входящий в комплект скрипт сравнивает два файла и классифицирует каждое различие по фиксированным правилам. Затем агент пишет, что каждое изменение значит для клиента: что он увидит и что ему придётся изменить.
Что агент пишет при каждом запуске
changes.jsonиchanges.csv: каждое различие с идентификатором, классом (ломающее, потенциально ломающее, неломающее, только документация), видом, методом и путём, а также старым и новым значением.change-report.mdиchange-report.html: сводные числа, затем ломающие изменения в первую очередь, каждое с указанием, где оно находится, что изменилось, что увидит клиент и что нужно изменить. HTML - это одна печатная страница без внешних файлов.migration-guide.md: шаги для разработчиков, которые вызывают API, с фрагментами «до» и «после», взятыми из двух файлов.changelog-entry.md: запись для журнала изменений и предлагаемое повышение версии с обоснованием. Решает команда.consumer-notice.md: короткое фактическое объявление для интеграторов.notes.md: что сравнивалось, чего сравнение двух файлов показать не может и что требует решения.
Правила, а не догадки
Скрипт знает 118 видов изменений в четырёх классах, с отдельными правилами для того, что клиент отправляет, и для того, что он получает: новое обязательное поле запроса - ломающее, новое поле ответа - нет. Он следует по локальным $ref. Запустите api_diff.py rules, чтобы прочитать все правила. Затем check подтверждает, что каждый ломающий идентификатор охвачен в отчёте и в руководстве.
Только ваши факты
Навык велит агенту брать фрагменты, пути и значения из ваших двух файлов, а то, что вы не предоставили, например дату отключения старой версии, помечать как [NEEDS: ...], а не выдумывать.
Честно об ограничениях
Он сравнивает два файла. Он не вызывает ваш API, поэтому поведение, которое описание не указывает, находится вне его поля зрения. Классы определяются правилами, и подтверждать их должна ваша команда. Обрабатываются только локальные $ref: спецификация, разбитая на несколько файлов, даёт предупреждение и неполное сравнение. Читатель YAML охватывает распространённое подмножество и называет строку, когда встречает что-то другое (преобразуйте этот файл в JSON). Регулярные выражения и oneOf / anyOf отмечаются как изменённые без вычисления. Заголовки ответов, ссылки, колбэки и вебхуки не сравниваются. Без спецификации агент может сравнить простой список эндпоинтов, который он строит по вашим файлам маршрутов; этот путь слабее и не прогонялся от начала до конца при тестировании. HTML-страницу проверяли чтением исходного кода, а не в браузере.
Арабский язык
По запросу отчёт, руководство и уведомление пишутся на арабском, а HTML-страница выводится справа налево, при этом пути и JSON остаются слева направо.
В комплекте: SKILL.md, четыре скрипта на Python со стандартной библиотекой, справочные материалы (правила, как писать каждую запись, форматы входных данных, заметки по арабскому), шаблоны и разобранный пример, который можно прочитать до покупки: платёжный API при переходе с 1.8.0 на 2.0.0, где 75 различий сгруппированы в 11 ломающих записей.
Проверено на двух случаях (платёжный API на OpenAPI 3 в YAML на английском; клинический API на Swagger 2.0 в JSON с отчётом на арабском). У скриптов 85 модульных тестов.
Кратко
Для бэкенд-разработчиков и команд API, которые выпускают новую версию и должны сообщить её пользователям, что изменилось.
Передайте своему агенту файл описания старой версии и файл новой версии (OpenAPI 3 или Swagger 2, в формате JSON или YAML). Он составит черновик отчёта об изменениях, руководства по миграции и уведомления для разработчиков, которые вы проверите до публикации.
Что пишет агент
- Файлы
changes.jsonиchanges.csv: каждое различие с номером, классом, местом, старым и новым значением. - Файл
change-report: сначала ломающие изменения, а при каждом из них - что увидит клиент и что ему нужно изменить. - Файл
migration-guide.md: шаги миграции с фрагментами «до» и «после», взятыми из ваших файлов. - Файлы
changelog-entry.mdиconsumer-notice.md: запись для журнала изменений и короткое уведомление.
Ограничения
Результаты - это изменения, которые потенциально могут быть ломающими и требуют проверки вашей командой. Навык сравнивает два файла и не вызывает API, поэтому то, чего описание не указывает, он не видит. Классификация основана на фиксированных правилах, и подтверждает её ваша команда. Он следует только по ссылкам внутри самого файла. Отчёт можно запросить на арабском со страницей справа налево; это пробовали на одном тестовом случае.
Вопросы
Какие форматы он читает?
OpenAPI 3.x и Swagger 2.0 в формате JSON или YAML. Читатель YAML охватывает распространённое подмножество и называет строку, если встречает неподдерживаемую возможность; преобразуйте этот файл в JSON.
Вызывает ли он мой API?
Нет. Он сравнивает два файла на вашем диске. Поведение, которое описание не указывает, находится вне его поля зрения.
Как он определяет, что ломающее?
По фиксированным правилам, которые можно прочитать командой rules: 118 видов изменений в четырёх классах, с отдельными правилами для того, что клиент отправляет, и для того, что он получает. Классы подтверждает ваша команда.
Что, если спецификация разбита на несколько файлов?
Обрабатываются только ссылки внутри одного файла. Сначала соберите спецификацию в один файл, иначе вы получите предупреждение и неполное сравнение.
Придумает ли он дату отключения?
Навык велит агенту этого не делать. Даты и сроки, которые вы не предоставили, помечаются [NEEDS: ...], чтобы вы их заполнили.
Может ли отчёт быть на арабском?
Да, как дополнительная возможность, со страницей HTML справа налево и путями, остающимися слева направо. Это пробовали на одном тестовом случае; прочитайте отчёт перед публикацией.
Что вы получите
1 файл · 76.62 KB
- api-change-report-1.0.0.zipZIP · 76.62 KB
ИИ-инструменты и скрипты
API Change Report: что может сломаться у потребителей вашего API, по двум спецификациям
Для команд API и агентств: скрипт сравнивает ваш старый и новый файл OpenAPI или Swagger по фиксированным правилам, а агент составляет отчёт о потенциально ломающих изменениях, руководство по миграции, запись для журнала изменений и уведомление для интеграторов, которые вы проверяете. Отчёт о том, что может сломаться у потребителей API между двумя версиями.
Getly открыл загруженные файлы и не нашёл ничего, что помешало бы их открыть. Это не проверка на вирусы и не оценка качества.
Теги
Частые вопросы
Доступ открывается сразу?
Да. Это цифровой товар - скачать его можно сразу после оплаты, прямо из своей библиотеки.
Можно ли использовать в коммерческих проектах?
Да. Коммерческое использование разрешено: в своём бизнесе и в том, что вы продаёте. Перепродавать и распространять сам файл нельзя.
Какие условия возврата?
Запросить возврат можно в течение 30 дней. Если что-то не так, оформите заявку в своём заказе - её рассмотрит команда Getly.
Какие форматы и размеры файлов я получу?
Вы скачаете 1 файл - ZIP - всего 76.62 KB.
Обновления бесплатны?
Да - когда продавец выпускает новую версию, вы можете бесплатно скачать актуальные файлы из своей библиотеки. Последние изменения смотрите в истории версий.
Цена
$7.00



