ШІ-інструменти та скрипти
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



