Läsa och uppdatera dokumentationen för ett importerat API

När du importerar en specifikation skapar Restorm inte bara begäranden: applikationen bevarar API:ets dokumentation — beskrivningar, modeller, säkerhetsscheman, exempel, uppräkningar — och fäster den vid den variabelmapp som importen skapar.

Nå dokumentationen

Fliken Docs i variabelmappen

Det är huvudvyn. Öppna variabelmappen som kommer från importen: dess rad med underflikar innehåller en flik Docs, vid sidan av Miljöer, Anpassade variabler och Anteckningar.

Fliken visas bara om mappen kommer från en import — en variabelmapp som du har skapat för hand har ingen dokumentation att visa.

De övriga ingångarna

Härifrån	Vad du får
Fliken Docs på en begäran	Dokumentationen för enbart den operationen — utan innehållsöversikt och utan block med allmän information. Den visas bara om operationen hittas i specifikationen
Fliken Docs i en vanlig mapp	Dokumentationen begränsad till de operationer som mappen innehåller
Variabelmappens startunderflik	Kortet Visa dokumentationen — ”Utforska API:ets dokumentation, modellerna och endpointerna”
Välkomstskärmen (API-kortet)	Snabblänken Dokumentation
Sökmotorn i titelraden	En förhandsvisning av dokumentationen när du hovrar över ett resultat

Vad vyn innehåller

Från topp till botten:

• API:ets titel och dess beskrivning;
• ett informationsblock: Version, Source format (med en länk till käll-URL:en), Server (scheman, värd, bassökväg), Contact, License, Terms of service, External docs;
• en sektion per tagg, med dess beskrivning;
• ett block per operation: metod och URL, sammanfattning, gruppmarkering, märket deprecated där det förekommer, sektionen Security (schematyp, OAuth 2-flöden, scopes) och en infällbar Example payload;
• tabellerna Parameters och Responses (statuskoderna är färgade);
• Models — en interaktiv graf över schemana, som går att navigera och zooma i;
• Polymorphism — kompositionerna oneOf / anyOf / allOf;
• Enums — uppräkningarna, sammanslagna med mappens egna.

Note

Rubrikerna på dessa sektioner (Models, Enums, Parameters, Responses, Security, Example payload) visas på engelska i alla applikationens språk. De återges som de är här så att du känner igen dem på skärmen.

Skapa en begäran från dokumentationen

Varje operationsblock har en knapp + Add som skapar en färdigkonfigurerad begäran för den operationen. Det är den kortaste vägen när en import blev ofullständig, eller när en operation just har dykt upp i specifikationen.

Navigera och söka

En innehållsöversikt är fäst till höger — sektionerna Overview, Operations, Models, Enums — infällbar och möjlig att ändra storlek på. Att klicka på en modell rullar ner till grafen och centrerar motsvarande nod där.

Kortkommando	Effekt
Ctrl+F / Cmd+F	Öppnar sökningen i dokumentationen
F3 / Enter	Nästa träff
Shift+F3 / Shift+Enter	Föregående träff
Esc	Stänger sökningen

En räknare visar var i resultaten du befinner dig.

Uppdatera dokumentationen

En specifikation utvecklas. Restorm kan hämta källan på nytt och tillämpa deltat — både dokumentation och begäranden — utan att skriva över ditt arbete.

Endast för importer via URL

Omsynkroniseringen är bara tillgänglig om mappen har importerats från en URL. En import från en fil eller genom inklistring sparar ingen källa, och uppdateringsknappen visas inte: startunderfliken visar då ”Den här mappen skapades inte från en importerbar källa.”

URL:en går inte att ändra i efterhand i gränssnittet. Gör en ny import om du vill byta källa.

Var knappen finns

Två likvärdiga ingångar:

1. variabelmappens startunderflik, sektionen Uppdateringar av specen — den visar URL, Senaste import och Senaste kontroll, och har knappen Uppdatera;
2. högerklick på mappen i sidoträdet → Uppdatera.

Det finns ingen automatisk kontroll

Restorm bevakar inte dina specifikationer i bakgrunden och meddelar dig inte att en ny version finns. Kontrollen startas alltid av dig.

Vad som händer

1. Ett fönster ”Uppdaterar specen …” visas under hämtningen. {{variables}} i URL:en och i headers löses upp, och den kopplade autentiseringsvägen körs först.
2. Restorm jämför ett fingeravtryck av den hämtade källan med det som sparades vid den senaste importen.
3. Ingenting har ändrats → ”API-specen är uppdaterad.”, och därmed är det klart.
4. Något har ändrats (eller hämtningen misslyckades) → guiden för omsynkronisering öppnas.

Guiden

• Käll-URL:en visas skrivskyddad.
• En markering låter dig koppla på, ändra eller koppla bort en autentiseringsväg, och undermenyn Custom headers låter dig lägga till fasta headers som skickas med vid varje uppdatering.
• Två förhandsvisningsflikar:
  • Routes — trädet över de operationer som hittats i den nya versionen, med filter och urval. De operationer som redan finns i din mapp är låsta och alltid ikryssade; du väljer bara vilka av de nya som ska läggas till;
  • Documentation — den nya versionens dokumentation, skrivskyddad, innan du bekräftar.
• Bekräftelseknappen visar antalet valda nya operationer, till exempel Apply update (3).

Note

Guiden visas i dag på engelska oavsett applikationens språk (”Refresh from source”, ”Apply update”, flikarna ”Routes” och ”Documentation”). De engelska rubrikerna återges därför som de är här.

Vad som ändras och vad som inte ändras

Det är den viktiga punkten: specifikationen bestämmer över det den beskriver, du bestämmer över resten.

Element	Beteende
En begärans namn	Ändras aldrig
Metod och URL	Ändras aldrig
Befintliga parametrar, headers och sökvägsparametrar	Behålls som de är — värde, beskrivning, aktivering
Parametrar som specifikationen lägger till	Läggs till, med specifikationens standardvärde eller tomma
Parametrar som tagits bort ur specifikationen	Behålls i begäran
Ny operation	Läggs till där en ny import skulle ha placerat den (inklusive taggmappen)
Operation som specifikationen märker som utfasad	Markeras; den visas nedtonad i trädet
Operation som försvunnit ur specifikationen	Markeras som borttagen; den visas överstruken i trädet, går fortfarande att köra och tas aldrig bort
API-dokumentation och uppräkningar	Ersätts helt av den nya versionen — det är så fliken Docs uppdateras

Ingenting tas någonsin bort ur ditt träd: en operation som försvinner ur källan markeras, den raderas inte.

Om källan kräver autentisering

Ett svar med 401 eller 403 öppnar guiden med felmeddelandet visat som det är (till exempel HTTP 401: Unauthorized). Koppla på en autentiseringsväg eller lägg till fasta headers, så körs förhandsvisningen om.

Format som går att synkronisera om

Tolv format har omsynkronisering: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC och Smithy.

För alla övriga skapar en ny import ett nytt träd. Den fullständiga listan finns i Uppdatera från källan.