Доступ до документації імпортованого API та її оновлення

Коли ви імпортуєте специфікацію, Restorm створює не лише запити: він зберігає документацію API — описи, моделі, схеми безпеки, приклади, переліки — і прикріплює її до теки середовищ, створеної імпортом.

Доступ до документації

Вкладка Docs теки середовищ

Це головне подання. Відкрийте теку середовищ, отриману з імпорту: у смузі її підвкладок є вкладка Docs поряд із Середовища, Власні змінні та Нотатки.

Вкладка з’являється, лише якщо тека походить з імпорту — тека середовищ, створена вами вручну, не має документації, яку можна показати.

Інші входи

Звідки	Що ви отримуєте
Вкладка Docs окремого запиту	Документацію лише цієї операції — без змісту та без блоку загальних відомостей. З’являється, лише якщо операцію знайдено в специфікації
Вкладка Docs простої теки	Документацію, обмежену операціями, які містить ця тека
Початкова підвкладка теки середовищ	Картку Переглянути документацію — «Ознайомтеся з документацією API, моделями та точками входу»
Екран привітання (картка API)	Швидке посилання Документація
Пошуковий рушій у рядку заголовка	Попередній перегляд документації під час наведення на результат

Що містить це подання

Згори донизу:

• назву API та її опис;
• блок відомостей: Version, Source format (з посиланням на URL джерела), Server (схеми, хост, базовий шлях), Contact, License, Terms of service, External docs;
• розділ на кожну мітку з її описом;
• блок на кожну операцію: метод і URL, стислий опис, позначку групи, значок deprecated, якщо він доречний, розділ Security (тип схеми, потоки OAuth 2, області) і згортний Example payload;
• таблиці Parameters і Responses (коди статусів розфарбовано);
• Models — інтерактивний граф схем, придатний до навігації та масштабування;
• Polymorphism — композиції oneOf / anyOf / allOf;
• Enums — переліки, злиті з переліками теки.

Note

Заголовки цих розділів (Models, Enums, Parameters, Responses, Security, Example payload) показуються англійською в усіх мовах застосунку. Тут вони наведені без змін, щоб ви впізнали їх на екрані.

Створення запиту з документації

Кожен блок операції має кнопку + Add, яка створює запит, заздалегідь налаштований для цієї операції. Це найкоротший шлях, коли імпорт був частковим або коли операція щойно з’явилася у специфікації.

Навігація та пошук

Зміст закріплено праворуч — розділи Overview, Operations, Models, Enums — його можна згортати й змінювати його розмір. Клацання на моделі прокручує сторінку до графа й центрує на відповідному вузлі.

Комбінація клавіш	Дія
Ctrl+F / Cmd+F	Відкриває пошук у документації
F3 / Enter	Наступний збіг
Shift+F3 / Shift+Enter	Попередній збіг
Esc	Закриває пошук

Лічильник показує позицію серед результатів.

Оновлення документації

Специфікація змінюється. Restorm уміє забрати джерело й застосувати різницю — і до документації, і до запитів — не перекреслюючи вашу роботу.

Лише для імпортів за URL

Повторна синхронізація доступна, лише якщо теку імпортовано за URL. Імпорт із файлу чи вставленням не записує джерела, і кнопка оновлення не з’являється: початкова підвкладка тоді показує «Цю теку не було створено з джерела, придатного до імпорту.»

Цей URL не можна змінити заднім числом в інтерфейсі. Щоб змінити джерело, зробіть імпорт заново.

Де кнопка

Два рівноцінні входи:

1. початкова підвкладка теки середовищ, розділ Оновлення специфікації — вона показує URL, Останній імпорт і Остання перевірка та містить кнопку Оновити;
2. клацання правою кнопкою на теці в бічному дереві → Оновити.

Автоматичної перевірки немає

Restorm не стежить за вашими специфікаціями у фоновому режимі й не попередить вас, що з’явилася нова версія. Перевірку завжди запускаєте ви.

Що відбувається

1. Під час отримання з’являється вікно «Оновлення специфікації…». {{variables}} в URL і заголовках обчислюються, а приєднаний маршрут автентифікації відпрацьовує заздалегідь.
2. Restorm порівнює відбиток отриманого джерела з відбитком, записаним під час останнього імпорту.
3. Нічого не змінилося → «Специфікація API актуальна.», і на цьому все.
4. Щось змінилося (або отримання не вдалося) → відкривається майстер повторної синхронізації.

Майстер

• URL джерела показано лише для читання.
• Окрема позначка дає змогу приєднати, змінити чи від’єднати маршрут автентифікації, а підменю Custom headers — додати сталі заголовки, які повторюються під час кожного оновлення.
• Дві вкладки попереднього перегляду:
  • Routes — дерево операцій, знайдених у новій версії, із фільтром і вибором. Операції, уже наявні у вашій теці, заблоковані й завжди позначені; ви обираєте лише те, які з нових додати;
  • Documentation — документація нової версії, лише для читання, перед підтвердженням.
• Кнопка підтвердження показує кількість вибраних нових операцій, наприклад Apply update (3).

Note

Майстер наразі показується англійською, хоч би якою була мова застосунку («Refresh from source», «Apply update», вкладки «Routes» і «Documentation»). Тому англійські заголовки тут наведено без змін.

Що змінюється, а що ні

Це головне: специфікація має владу над тим, що вона описує, а ви — над усім іншим.

Елемент	Поведінка
Назва запиту	Ніколи не змінюється
Метод і URL	Ніколи не змінюються
Наявні параметри, заголовки та параметри шляху	Зберігаються як є — значення, опис, увімкненість
Параметри, додані специфікацією	Додаються зі значенням за замовчуванням зі специфікації або порожніми
Параметри, вилучені зі специфікації	Зберігаються в запиті
Нова операція	Додається туди, куди її помістив би свіжий імпорт (включно з текою мітки)
Операція, позначена специфікацією як застаріла	Відзначається; у дереві показується приглушено
Операція, що зникла зі специфікації	Відзначається як вилучена; у дереві показується закреслено, залишається виконуваною й ніколи не видаляється
Документація API та переліки	Замінюються повністю новою версією — саме це оновлює вкладку Docs

З вашого дерева нічого ніколи не видаляється: операція, що зникла з джерела, позначається, а не стирається.

Якщо джерело вимагає автентифікації

Відповідь 401 чи 403 відкриває майстер із повідомленням про помилку, показаним як є (наприклад, HTTP 401: Unauthorized). Приєднайте маршрут автентифікації або додайте сталі заголовки — і попередній перегляд запуститься знову.

Формати, придатні до повторної синхронізації

Повторну синхронізацію мають дванадцять форматів: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC і Smithy.

Для всіх інших новий імпорт створює нове дерево. Повний перелік є на сторінці Оновлення з джерела.