Adgang til og opdatering af dokumentationen for et importeret API

Når du importerer en specifikation, opretter Restorm ikke kun anmodninger: den bevarer API’ets dokumentation — beskrivelser, modeller, sikkerhedsskemaer, eksempler, opremsninger — og knytter den til den miljømappe, importen har oprettet.

Sådan får du fat i dokumentationen

Fanen Docs i miljømappen

Det er hovedvisningen. Åbn den miljømappe, importen har lavet: dens underfanelinje har en Docs-fane ved siden af Miljøer, Brugerdefinerede variabler og Noter.

Fanen vises kun, hvis mappen stammer fra en import — en miljømappe, du selv har oprettet i hånden, har ingen dokumentation at vise.

De øvrige adgangsveje

Fra	Hvad du får
Fanen Docs på en anmodning	Dokumentationen for netop den ene operation — uden indholdsfortegnelse og uden blokken med generelle oplysninger. Den vises kun, hvis operationen kan findes i specifikationen
Fanen Docs på en almindelig mappe	Dokumentationen begrænset til de operationer, mappen indeholder
Miljømappens startunderfane	Kortet Se dokumentationen — »Gennemse API’ets dokumentation, modeller og endpoints«
Startskærmen (API-kortet)	Genvejen Dokumentation
Søgemaskinen i titellinjen	Et eksempel på dokumentationen, når du holder musen over et resultat

Hvad visningen indeholder

Oppefra og ned:

• API’ets titel og dets beskrivelse;
• en informationsblok: Version, Source format (med et link til kilde-URL’en), Server (skemaer, vært, basissti), Contact, License, Terms of service, External docs;
• ét afsnit pr. tag med dets beskrivelse;
• én blok pr. operation: metode og URL, resumé, gruppeprik, badget deprecated hvis relevant, afsnittet Security (skematype, OAuth 2-flow, scopes) og en sammenklappelig Example payload;
• tabellerne Parameters og Responses (statuskoderne er farvede);
• Models — en interaktiv graf over skemaerne, som kan navigeres og zoomes;
• Polymorphism — kompositionerne oneOf / anyOf / allOf;
• Enums — opremsningerne, flettet sammen med mappens egne.

Note

Betegnelserne på disse afsnit (Models, Enums, Parameters, Responses, Security, Example payload) vises på engelsk på alle applikationens sprog. De er gengivet uændret her, så du kan genkende dem på skærmen.

Opret en anmodning ud fra dokumentationen

Hver operationsblok har en + Add-knap, der opretter en anmodning, som på forhånd er konfigureret til den operation. Det er den korteste vej, når en import kun blev delvis, eller når en operation lige er dukket op i specifikationen.

Naviger og søg

En indholdsfortegnelse er forankret til højre — afsnittene Overview, Operations, Models, Enums — og kan klappes sammen og ændres i størrelse. Klikker du på en model, rulles der ned til grafen, og den tilsvarende knude centreres.

Genvej	Virkning
Ctrl+F / Cmd+F	Åbner søgningen i dokumentationen
F3 / Enter	Næste match
Shift+F3 / Shift+Enter	Forrige match
Esc	Lukker søgningen

En tæller viser positionen i resultaterne.

Opdatér dokumentationen

En specifikation ændrer sig. Restorm kan hente kilden igen og anvende forskellen — både dokumentation og anmodninger — uden at overskrive dit arbejde.

Kun for import via URL

Gensynkronisering er kun tilgængelig, hvis mappen blev importeret fra en URL. En import fra en fil eller ved indsætning gemmer ingen kilde, og opdateringsknappen dukker ikke op: startunderfanen viser da »Denne mappe er ikke oprettet ud fra en kilde, der kan importeres.«

Denne URL kan ikke ændres bagefter i brugerfladen. Vil du skifte kilde, så lav importen om.

Hvor knappen er

To indgange, der svarer til hinanden:

1. miljømappens startunderfane, afsnittet Opdateringer af API-spec — den viser URL, Senest importeret og Senest kontrolleret og har knappen Opdater;
2. højreklik på mappen i sidepanelets træstruktur → Opdater.

Der er ingen automatisk kontrol

Restorm holder ikke øje med dine specifikationer i baggrunden og fortæller dig ikke, at en ny version er tilgængelig. Kontrollen udløses altid af dig.

Hvad der sker

1. Et vindue, »Opdaterer API-spec …«, dukker op, mens der hentes. {{variables}} i URL’en og i headerne opløses, og den tilknyttede godkendelsesrute køres på forhånd.
2. Restorm sammenligner et fingeraftryk af den hentede kilde med det, der blev gemt ved den seneste import.
3. Intet har ændret sig → »API-speccen er opdateret.«, og så er det slut.
4. Noget har ændret sig (eller hentningen slog fejl) → guiden til gensynkronisering åbnes.

Guiden

• Kilde-URL’en vises skrivebeskyttet.
• En prik gør det muligt at knytte, ændre eller frakoble en godkendelsesrute, og undermenuen Custom headers lader dig tilføje faste headere, som køres med ved hver opdatering.
• To forhåndsvisningsfaner:
  • Routes — træet over de operationer, der findes i den nye version, med filter og markering. De operationer, der allerede findes i din mappe, er låst og altid afkrydset; du vælger kun, hvilke af de nye der skal tilføjes;
  • Documentation — dokumentationen for den nye version, skrivebeskyttet, inden du bekræfter.
• Bekræftelsesknappen viser antallet af valgte nye operationer, for eksempel Apply update (3).

Note

Guiden vises i dag på engelsk, uanset applikationens sprog (»Refresh from source«, »Apply update«, fanerne »Routes« og »Documentation«). De engelske betegnelser er derfor gengivet uændret her.

Hvad der ændres, og hvad der ikke gør

Det er det vigtige punkt: specifikationen bestemmer over det, den beskriver, og du bestemmer over resten.

Element	Opførsel
En anmodnings navn	Ændres aldrig
Metode og URL	Ændres aldrig
Eksisterende parametre, headere og stiparametre	Bevares, som de er — værdi, beskrivelse, aktivering
Parametre, som specifikationen tilføjer	Tilføjes, med specifikationens standardværdi eller tomme
Parametre, som er fjernet fra specifikationen	Bevares på anmodningen
En ny operation	Tilføjes dér, hvor en helt ny import ville have lagt den (inklusive tagmappen)
En operation, specifikationen markerer som forældet	Markeres; den vises nedtonet i træstrukturen
En operation, der er forsvundet fra specifikationen	Markeres som fjernet; den vises overstreget i træstrukturen, kan stadig køres og slettes aldrig
API-dokumentation og opremsninger	Erstattes helt af den nye version — det er dét, der opdaterer Docs-fanen

Der slettes aldrig noget fra din træstruktur: en operation, der forsvinder fra kilden, markeres, den fjernes ikke.

Hvis kilden kræver godkendelse

Et 401- eller 403-svar åbner guiden med fejlmeddelelsen vist, som den er (for eksempel HTTP 401: Unauthorized). Knyt en godkendelsesrute til, eller tilføj faste headere, hvorefter forhåndsvisningen køres igen.

Formater, der kan gensynkroniseres

Tolv formater kan gensynkroniseres: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC og Smithy.

For alle de øvrige opretter en ny import en ny træstruktur. Hele listen står i Opdatér fra kilden.