Zugriff auf und Aktualisierung der Dokumentation einer importierten API

Beim Import einer Spezifikation erzeugt Restorm nicht nur Anfragen: Es bewahrt die API-Dokumentation – Beschreibungen, Modelle, Sicherheitsschemata, Beispiele, Aufzählungen – und hängt sie an den durch den Import erzeugten Variablenordner an.

Auf die Dokumentation zugreifen

Der Tab Docs des Variablenordners

Das ist die Hauptansicht. Öffnen Sie den aus dem Import stammenden Variablenordner: Seine Unter-Tab-Leiste trägt einen Tab Docs, neben Environnements, Variables personnalisées und Notes.

Der Tab erscheint nur, wenn der Ordner aus einem Import stammt – ein von Hand erstellter Variablenordner hat keine Dokumentation anzuzeigen.

Die weiteren Zugänge

Von	Was Sie erhalten
Der Tab Docs einer Anfrage	Die Dokumentation nur dieser einen Operation – ohne Verzeichnis oder allgemeinen Informationsblock. Er erscheint nur, wenn die Operation in der Spezifikation wiedergefunden wird
Der Tab Docs eines einfachen Ordners	Die auf die in diesem Ordner enthaltenen Operationen beschränkte Dokumentation
Der Startseiten-Unter-Tab des Variablenordners	Die Karte Dokumentation ansehen – „Durchsuchen Sie die API-Dokumentation, die Modelle und die Endpunkte“
Der Startbildschirm (API-Karte)	Der Schnelllink Dokumentation
Die Suche der Titelleiste	Eine Vorschau der Dokumentation beim Überfahren eines Ergebnisses

Was die Ansicht enthält

Von oben nach unten:

• der Titel der API und ihre Beschreibung;
• ein Informationsblock: Version, Source format (mit einem Link zur Quell-URL), Server (Schemata, Host, Basispfad), Contact, License, Terms of service, External docs;
• ein Abschnitt pro Tag, mit seiner Beschreibung;
• ein Block pro Operation: Methode und URL, Zusammenfassung, Gruppen-Pastille, gegebenenfalls Badge deprecated, Abschnitt Security (Schematyp, OAuth-2-Flows, Scopes) und ein einklappbares Example payload;
• die Tabellen Parameters und Responses (die Statuscodes sind eingefärbt);
• Models – ein interaktiver Graph der Schemata, navigierbar und zoombar;
• Polymorphism – die Kompositionen oneOf / anyOf / allOf;
• Enums – die Aufzählungen, zusammengeführt mit denen des Ordners.

Note

Die Bezeichnungen dieser Abschnitte (Models, Enums, Parameters, Responses, Security, Example payload) werden in allen Sprachen der Anwendung auf Englisch angezeigt. Sie werden hier unverändert übernommen, damit Sie sie am Bildschirm wiedererkennen.

Eine Anfrage aus der Dokumentation erstellen

Jeder Operationsblock trägt eine Schaltfläche + Add, die eine für diese Operation vorkonfigurierte Anfrage erstellt. Das ist der kürzeste Weg, wenn ein Import unvollständig war oder wenn eine Operation gerade erst in der Spezifikation aufgetaucht ist.

Navigieren und suchen

Ein Verzeichnis ist rechts verankert – Abschnitte Overview, Operations, Models, Enums – einklappbar und größenveränderbar. Ein Klick auf ein Modell scrollt zum Graphen und zentriert dort den entsprechenden Knoten.

Tastenkürzel	Wirkung
Ctrl+F / Cmd+F	Öffnet die Suche in der Dokumentation
F3 / Enter	Nächster Treffer
Shift+F3 / Shift+Enter	Vorheriger Treffer
Esc	Schließt die Suche

Ein Zähler zeigt die Position innerhalb der Ergebnisse an.

Die Dokumentation aktualisieren

Eine Spezifikation entwickelt sich weiter. Restorm kann die Quelle erneut abrufen und das Delta anwenden – Dokumentation und Anfragen –, ohne Ihre Arbeit zu überschreiben.

Nur für per URL importierte Inhalte

Die Resynchronisation ist nur verfügbar, wenn der Ordner von einer URL importiert wurde. Ein Import aus einer Datei oder per Einfügen speichert keine Quelle, und die Aktualisierungsschaltfläche erscheint nicht: Der Startseiten-Unter-Tab zeigt dann „Dieser Ordner wurde nicht aus einer importierbaren Quelle erstellt.“

Diese URL ist im Nachhinein nicht in der Oberfläche änderbar. Um die Quelle zu wechseln, führen Sie einen erneuten Import durch.

Wo sich die Schaltfläche befindet

Zwei gleichwertige Einträge:

1. der Startseiten-Unter-Tab des Variablenordners, Abschnitt Spezifikations-Updates – er zeigt die URL, den Letzten Import und die Letzte Prüfung an und trägt die Schaltfläche Aktualisieren;
2. der Rechtsklick auf den Ordner in der Seitenleiste → Aktualisieren.

Es gibt keine automatische Prüfung

Restorm überwacht Ihre Spezifikationen nicht im Hintergrund und benachrichtigt Sie nicht, wenn eine neue Version verfügbar ist. Die Prüfung wird immer von Ihnen ausgelöst.

Was passiert

1. Ein Fenster „Aktualisierung der Spezifikation …“ erscheint während des Abrufs. Die {{variables}} der URL und der Header werden aufgelöst, und die angehängte Authentifizierungsroute wird vorab ausgeführt.
2. Restorm vergleicht einen Fingerabdruck der abgerufenen Quelle mit dem beim letzten Import gespeicherten.
3. Nichts hat sich geändert → „Die API-Spezifikation ist aktuell.“, und der Vorgang ist beendet.
4. Etwas hat sich geändert (oder der Abruf ist fehlgeschlagen) → der Resynchronisationsassistent öffnet sich.

Der Assistent

• Die Quell-URL wird schreibgeschützt angezeigt.
• Eine Pastille erlaubt es, eine Authentifizierungsroute anzuhängen, zu ändern oder zu entfernen, und ein Untermenü Custom headers, feste Header hinzuzufügen, die bei jeder Aktualisierung erneut mitgeschickt werden.
• Zwei Vorschau-Tabs:
  • Routes – der Baum der in der neuen Version gefundenen Operationen, mit Filter und Auswahl. Die bereits vorhandenen Operationen in Ihrem Ordner sind gesperrt und immer angehakt; Sie wählen nur aus, welche der neuen hinzugefügt werden;
  • Documentation – die Dokumentation der neuen Version, schreibgeschützt, vor der Bestätigung.
• Die Bestätigungsschaltfläche zeigt die Anzahl der ausgewählten neuen Operationen an, zum Beispiel Apply update (3).

Note

Der Assistent wird derzeit unabhängig von der Sprache der Anwendung auf Englisch angezeigt („Refresh from source“, „Apply update“, Tabs „Routes“ und „Documentation“). Die englischen Bezeichnungen werden hier daher unverändert übernommen.

Was geändert wird, und was nicht

Das ist der wichtige Punkt: Die Spezifikation ist maßgeblich für das, was sie beschreibt, Sie sind maßgeblich für den Rest.

Element	Verhalten
Name einer Anfrage	Nie geändert
Methode und URL	Nie geändert
Bestehende Parameter, Header und Pfadparameter	Unverändert beibehalten – Wert, Beschreibung, Aktivierung
Von der Spezifikation hinzugefügte Parameter	Hinzugefügt, mit dem Standardwert der Spezifikation oder leer
Aus der Spezifikation entfernte Parameter	Bei der Anfrage beibehalten
Neue Operation	An der Stelle hinzugefügt, an der sie ein neuer Import platziert hätte (einschließlich Tag-Ordner)
Von der Spezifikation als veraltet markierte Operation	Markiert; sie erscheint abgeblendet im Baum
Aus der Spezifikation verschwundene Operation	Als entfernt markiert; sie erscheint durchgestrichen im Baum, bleibt ausführbar und wird nie gelöscht
API-Dokumentation und Aufzählungen	Vollständig durch die neue Version ersetzt – das ist es, was den Tab Docs aktualisiert

Aus Ihrem Baum wird nie etwas gelöscht: Eine Operation, die aus der Quelle verschwindet, wird markiert, nicht entfernt.

Wenn die Quelle eine Authentifizierung verlangt

Eine Antwort 401 oder 403 öffnet den Assistenten mit der unverändert angezeigten Fehlermeldung (zum Beispiel HTTP 401: Unauthorized). Hängen Sie eine Authentifizierungsroute an oder fügen Sie feste Header hinzu, und die Vorschau wird erneut ausgeführt.

Resynchronisierbare Formate

Zwölf Formate verfügen über die Resynchronisation: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC und Smithy.

Für alle anderen erzeugt ein erneuter Import einen neuen Baum. Die vollständige Liste finden Sie unter Aktualisierung aus der Quelle.