Toegang tot en bijwerken van de documentatie van een geïmporteerde API

Wanneer u een specificatie importeert, maakt Restorm niet alleen verzoeken: het bewaart de documentatie van de API — beschrijvingen, modellen, beveiligingsschema’s, voorbeelden, enumeraties — en koppelt die aan de omgevingsmap die de import heeft aangemaakt.

Bij de documentatie komen

Het tabblad Docs van de omgevingsmap

Dat is de hoofdweergave. Open de omgevingsmap die uit de import komt: de balk met subtabbladen bevat een tabblad Docs, naast Omgevingen, Aangepaste variabelen en Aantekeningen.

Het tabblad verschijnt alleen als de map uit een import komt — een omgevingsmap die u zelf hebt gemaakt, heeft geen documentatie om te tonen.

De andere ingangen

Vanuit	Wat u krijgt
Het tabblad Docs van een verzoek	De documentatie van die ene operatie — zonder inhoudsopgave en zonder het blok met algemene informatie. Het verschijnt alleen als de operatie in de specificatie wordt teruggevonden
Het tabblad Docs van een gewone map	De documentatie, beperkt tot de operaties die deze map bevat
Het starttabblad van de omgevingsmap	De kaart De documentatie bekijken — “Verken de documentatie van de API, de modellen en de endpoints”
Het welkomstscherm (API-kaart)	De snelkoppeling Documentatie
De zoekmachine in de titelbalk	Een voorbeeld van de documentatie wanneer u met de muis over een resultaat gaat

Wat de weergave bevat

Van boven naar onder:

• de titel van de API en de beschrijving daarvan;
• een informatieblok: Version, Source format (met een link naar de bron-URL), Server (schema’s, host, basispad), Contact, License, Terms of service, External docs;
• één sectie per label, met de beschrijving daarvan;
• één blok per operatie: methode en URL, samenvatting, groepsstip, eventueel een badge deprecated, een sectie Security (type schema, OAuth 2-flows, scopes), en een uitvouwbaar Example payload;
• de tabellen Parameters en Responses (de statuscodes zijn gekleurd);
• Models — een interactieve graaf van de schema’s, waarin u kunt navigeren en zoomen;
• Polymorphism — de composities oneOf / anyOf / allOf;
• Enums — de enumeraties, samengevoegd met die van de map.

Note

De opschriften van deze secties (Models, Enums, Parameters, Responses, Security, Example payload) worden in alle talen van de applicatie in het Engels weergegeven. Ze zijn hier ongewijzigd overgenomen zodat u ze op het scherm terugvindt.

Een verzoek maken vanuit de documentatie

Elk operatieblok heeft een knop + Add die een verzoek maakt dat voor deze operatie is voorgeconfigureerd. Dat is de kortste weg wanneer een import gedeeltelijk is gebleven, of wanneer er net een operatie in de specificatie is bijgekomen.

Navigeren en zoeken

Rechts is een inhoudsopgave vastgezet — de secties Overview, Operations, Models, Enums — die u kunt samenvouwen en van grootte veranderen. Op een model klikken schuift naar de graaf en centreert daar de bijbehorende node.

Sneltoets	Effect
Ctrl+F / Cmd+F	Opent de zoekfunctie in de documentatie
F3 / Enter	Volgende overeenkomst
Shift+F3 / Shift+Enter	Vorige overeenkomst
Esc	Sluit de zoekfunctie

Een teller geeft de positie in de resultaten aan.

De documentatie bijwerken

Een specificatie verandert. Restorm kan de bron opnieuw ophalen en het verschil toepassen — documentatie en verzoeken — zonder uw werk te overschrijven.

Uitsluitend voor imports via een URL

De hersynchronisatie is alleen beschikbaar als de map vanaf een URL is geïmporteerd. Een import vanuit een bestand of via plakken legt geen bron vast, en de vernieuwknop verschijnt dan niet: het starttabblad toont in dat geval “Deze map is niet vanuit een importeerbare bron aangemaakt.”

Die URL is achteraf niet te wijzigen in de interface. Om van bron te veranderen, importeert u opnieuw.

Waar de knop staat

Er zijn twee gelijkwaardige ingangen:

1. het starttabblad van de omgevingsmap, sectie Updates van de spec — die toont de URL, de Laatste import en de Laatste controle, en bevat de knop Vernieuwen;
2. rechtsklikken op de map in de zijboom → Vernieuwen.

Er is geen automatische controle

Restorm houdt uw specificaties niet op de achtergrond in de gaten en waarschuwt u niet dat er een nieuwe versie beschikbaar is. De controle wordt altijd door u gestart.

Wat er gebeurt

1. Er verschijnt een venster “De spec vernieuwen…” tijdens het ophalen. De {{variabelen}} in de URL en de headers worden opgelost, en de gekoppelde authenticatieroute wordt vooraf gespeeld.
2. Restorm vergelijkt een vingerafdruk van de opgehaalde bron met de vingerafdruk die bij de laatste import is vastgelegd.
3. Niets is veranderd → “De spec van de API is up-to-date.”, en daarmee is het klaar.
4. Er is iets veranderd (of het ophalen is mislukt) → de wizard voor hersynchronisatie opent.

De wizard

• De bron-URL wordt alleen-lezen weergegeven.
• Met een knop kunt u een authenticatieroute koppelen, wijzigen of losmaken, en met een submenu Custom headers kunt u vaste headers toevoegen die bij elke vernieuwing worden meegestuurd.
• Er zijn twee voorbeeldtabbladen:
  • Routes — de boom met de operaties die in de nieuwe versie zijn gevonden, met een filter en een selectie. De operaties die al aanwezig zijn in uw map, zijn vergrendeld en altijd aangevinkt; u kiest alleen welke van de nieuwe u toevoegt;
  • Documentation — de documentatie van de nieuwe versie, alleen-lezen, voordat u bevestigt.
• De bevestigingsknop toont het aantal geselecteerde nieuwe operaties, bijvoorbeeld Apply update (3).

Note

De wizard wordt vandaag in het Engels weergegeven, wat de taal van de applicatie ook is (“Refresh from source”, “Apply update”, de tabbladen “Routes” en “Documentation”). De Engelse opschriften zijn hier dus ongewijzigd overgenomen.

Wat er wordt gewijzigd, en wat niet

Dit is het belangrijke punt: de specificatie heeft gezag over wat zij beschrijft, en u hebt gezag over de rest.

Element	Gedrag
De naam van een verzoek	Nooit gewijzigd
Methode en URL	Nooit gewijzigd
Bestaande parameters, headers en padparameters	Ongewijzigd bewaard — waarde, beschrijving, activering
Parameters die de specificatie toevoegt	Toegevoegd, met de standaardwaarde uit de specificatie of leeg
Parameters die uit de specificatie zijn verwijderd	Blijven op het verzoek staan
Nieuwe operatie	Toegevoegd op de plek waar een verse import haar zou hebben gezet (inclusief de labelmap)
Operatie die de specificatie als verouderd markeert	Gemarkeerd; zij verschijnt gedempt in de boom
Operatie die uit de specificatie is verdwenen	Gemarkeerd als verwijderd; zij verschijnt doorgestreept in de boom, blijft uitvoerbaar en wordt nooit verwijderd
API-documentatie en enumeraties	Volledig vervangen door de nieuwe versie — dat is wat het tabblad Docs vernieuwt

Er wordt nooit iets uit uw boom verwijderd: een operatie die uit de bron verdwijnt, wordt gemarkeerd, niet gewist.

Als de bron authenticatie vraagt

Een respons 401 of 403 opent de wizard met de foutmelding ongewijzigd weergegeven (bijvoorbeeld HTTP 401: Unauthorized). Koppel een authenticatieroute of voeg vaste headers toe, en het voorbeeld wordt opnieuw opgehaald.

Formaten die opnieuw te synchroniseren zijn

Twaalf formaten beschikken over de hersynchronisatie: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC en Smithy.

Voor alle andere maakt een nieuwe import een nieuwe boom. De volledige lijst staat in Bijwerken vanaf de bron.