Dostęp do dokumentacji zaimportowanego API i jej aktualizacja

Przy imporcie specyfikacji Restorm nie tworzy wyłącznie żądań: zachowuje też dokumentację API — opisy, modele, schematy zabezpieczeń, przykłady, wyliczenia — i dołącza ją do folderu zmiennych utworzonego przez import.

Dostęp do dokumentacji

Zakładka Docs folderu zmiennych

To widok główny. Po otwarciu folderu zmiennych pochodzącego z importu na jego pasku podzakładek widoczna jest zakładka Docs, obok Środowisk, Zmiennych własnych i Notatek.

Zakładka pojawia się tylko wtedy, gdy folder pochodzi z importu — folder zmiennych utworzony ręcznie nie ma dokumentacji do wyświetlenia.

Pozostałe drogi dostępu

Skąd	Co się otrzymuje
Zakładka Docs w żądaniu	Dokumentacja tylko tej jednej operacji — bez spisu treści i bez bloku informacji ogólnych. Pojawia się jedynie wtedy, gdy operacja zostanie odnaleziona w specyfikacji
Zakładka Docs w zwykłym folderze	Dokumentacja ograniczona do operacji zawartych w tym folderze
Startowa podzakładka folderu zmiennych	Karta Zobacz dokumentację — „Przeglądaj dokumentację API, modele i punkty końcowe”
Ekran powitalny (karta API)	Szybki link Dokumentacja
Wyszukiwarka na pasku tytułu	Podgląd dokumentacji po najechaniu kursorem na wynik

Co zawiera ten widok

Od góry do dołu:

• tytuł API i jego opis;
• blok informacyjny: Version, Source format (z odnośnikiem do źródłowego adresu URL), Server (schematy, host, ścieżka bazowa), Contact, License, Terms of service, External docs;
• jedna sekcja na każdą etykietę, wraz z jej opisem;
• jeden blok na każdą operację: metoda i adres URL, streszczenie, plakietka grupy, w stosownych przypadkach plakietka deprecated, sekcja Security (typ schematu, przepływy OAuth 2, zakresy) oraz zwijany Example payload;
• tabele Parameters i Responses (kody statusu są kolorowane);
• Models — interaktywny graf schematów, po którym można się przemieszczać i który można powiększać;
• Polymorphism — kompozycje oneOf / anyOf / allOf;
• Enums — wyliczenia, scalone z wyliczeniami folderu.

Note

Nazwy tych sekcji (Models, Enums, Parameters, Responses, Security, Example payload) są wyświetlane po angielsku we wszystkich językach aplikacji. Zostały tu przytoczone w niezmienionej formie, aby dały się rozpoznać na ekranie.

Tworzenie żądania z dokumentacji

Każdy blok operacji zawiera przycisk + Add, który tworzy żądanie wstępnie skonfigurowane dla tej operacji. To najkrótsza droga, gdy import był częściowy albo gdy jakaś operacja właśnie pojawiła się w specyfikacji.

Nawigacja i wyszukiwanie

Po prawej stronie zakotwiczony jest spis treści — sekcje Overview, Operations, Models, Enums — zwijany i o regulowanej szerokości. Kliknięcie modelu przewija widok do grafu i centruje w nim odpowiedni węzeł.

Skrót	Działanie
Ctrl+F / Cmd+F	Otwiera wyszukiwanie w dokumentacji
F3 / Enter	Następne trafienie
Shift+F3 / Shift+Enter	Poprzednie trafienie
Esc	Zamyka wyszukiwanie

Licznik wskazuje pozycję wśród wyników.

Aktualizacja dokumentacji

Specyfikacja się zmienia. Restorm potrafi ponownie pobrać źródło i zastosować deltę — zarówno do dokumentacji, jak i do żądań — bez nadpisywania wykonanej pracy.

Tylko dla importów przez adres URL

Ponowna synchronizacja jest dostępna wyłącznie wtedy, gdy folder został zaimportowany z adresu URL. Import z pliku lub przez wklejenie nie zapisuje źródła i przycisk odświeżania się nie pojawia: startowa podzakładka wyświetla wówczas „Ten folder nie został utworzony na podstawie importowalnego źródła.”

Tego adresu URL nie można później zmienić w interfejsie. Aby zmienić źródło, trzeba wykonać import ponownie.

Gdzie znajduje się przycisk

Dwa równoważne punkty wejścia:

1. startowa podzakładka folderu zmiennych, sekcja Aktualizacje specyfikacji — wyświetla URL, Ostatni import oraz Ostatnie sprawdzenie i zawiera przycisk Odśwież;
2. kliknięcie folderu prawym przyciskiem w drzewie panelu bocznego → Odśwież.

Nie ma automatycznego sprawdzania

Restorm nie monitoruje specyfikacji w tle i nie powiadomi o dostępności nowej wersji. Sprawdzenie jest zawsze uruchamiane przez użytkownika.

Co się dzieje

1. Na czas pobierania pojawia się okno „Odświeżanie specyfikacji…”. {{variables}} z adresu URL i z nagłówków są rozwiązywane, a dołączona trasa uwierzytelniania jest odtwarzana wcześniej.
2. Restorm porównuje odcisk pobranego źródła z odciskiem zapisanym przy ostatnim imporcie.
3. Nic się nie zmieniło → „Specyfikacja API jest aktualna.” i na tym koniec.
4. Coś się zmieniło (albo pobranie się nie udało) → otwiera się kreator ponownej synchronizacji.

Kreator

• Źródłowy adres URL jest wyświetlany tylko do odczytu.
• Plakietka pozwala dołączyć, zmienić lub odłączyć trasę uwierzytelniania, a podmenu Custom headers — dodać stałe nagłówki odtwarzane przy każdym odświeżeniu.
• Dwie zakładki podglądu:
  • Routes — drzewo operacji znalezionych w nowej wersji, z filtrem i wyborem. Operacje już obecne w folderze są zablokowane i zawsze zaznaczone; wybiera się jedynie, które z nowych dodać;
  • Documentation — dokumentacja nowej wersji, tylko do odczytu, przed zatwierdzeniem.
• Przycisk zatwierdzenia pokazuje liczbę wybranych nowych operacji, na przykład Apply update (3).

Note

Kreator jest dziś wyświetlany po angielsku niezależnie od języka aplikacji („Refresh from source”, „Apply update”, zakładki „Routes” i „Documentation”). Angielskie nazwy zostały więc przytoczone tutaj w niezmienionej formie.

Co jest zmieniane, a co nie

To najważniejszy punkt: specyfikacja rozstrzyga o tym, co opisuje, użytkownik rozstrzyga o całej reszcie.

Element	Zachowanie
Nazwa żądania	Nigdy nie jest zmieniana
Metoda i adres URL	Nigdy nie są zmieniane
Istniejące parametry, nagłówki i parametry ścieżki	Zachowane bez zmian — wartość, opis, włączenie
Parametry dodane przez specyfikację	Dodane, z wartością domyślną ze specyfikacji albo puste
Parametry usunięte ze specyfikacji	Zachowane w żądaniu
Nowa operacja	Dodana tam, gdzie umieściłby ją świeży import (wraz z folderem etykiety)
Operacja oznaczona przez specyfikację jako przestarzała	Zasygnalizowana; w drzewie jest przygaszona
Operacja, która zniknęła ze specyfikacji	Zasygnalizowana jako usunięta; w drzewie jest przekreślona, pozostaje wykonywalna i nigdy nie jest usuwana
Dokumentacja API i wyliczenia	Zastąpione w całości nową wersją — to właśnie odświeża zakładkę Docs

Nic nigdy nie jest usuwane z drzewa projektu: operacja, która zniknęła ze źródła, zostaje oznaczona, a nie wymazana.

Jeśli źródło wymaga uwierzytelnienia

Odpowiedź 401 lub 403 otwiera kreator z komunikatem błędu wyświetlonym w niezmienionej formie (na przykład HTTP 401: Unauthorized). Wystarczy dołączyć trasę uwierzytelniania albo dodać stałe nagłówki, a podgląd zostanie uruchomiony ponownie.

Formaty z ponowną synchronizacją

Ponowną synchronizację obsługuje dwanaście formatów: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC i Smithy.

W przypadku wszystkich pozostałych nowy import tworzy nowe drzewo. Pełna lista znajduje się na stronie Aktualizacja ze źródła.