Tilgang til og oppdatering av dokumentasjonen for et importert API

Når du importerer en spesifikasjon, lager Restorm ikke bare forespørsler: den beholder API-dokumentasjonen — beskrivelser, modeller, sikkerhetsskjemaer, eksempler og enumerasjoner — og knytter den til miljømappen som importen opprettet.

Få tilgang til dokumentasjonen

Docs-fanen i miljømappen

Dette er hovedvisningen. Åpne miljømappen som importen ga: underfanelinjen der har en Docs-fane, ved siden av Miljøer, Custom variables og Notater.

Fanen vises bare hvis mappen kommer fra en import — en miljømappe du har laget for hånd, har ingen dokumentasjon å vise.

De andre inngangene

Fra	Hva du får
Docs-fanen på en forespørsel	Dokumentasjonen for bare denne operasjonen — uten innholdsfortegnelse og uten blokken med generell informasjon. Den vises bare hvis operasjonen finnes igjen i spesifikasjonen
Docs-fanen i en vanlig mappe	Dokumentasjonen begrenset til operasjonene som ligger i mappen
Startunderfanen i miljømappen	Kortet Vis dokumentasjon — «Bla gjennom API-dokumentasjon, modeller og endepunkter»
Startskjermen (API-kortet)	Hurtiglenken Dokumentasjon
Søkemotoren i tittellinjen	En forhåndsvisning av dokumentasjonen når du holder pekeren over et treff

Hva visningen inneholder

Ovenfra og ned:

• tittelen på API-et og beskrivelsen av det;
• en informasjonsblokk: Version, Source format (med en lenke til kilde-URL-en), Server (protokoller, vert, basissti), Contact, License, Terms of service, External docs;
• en seksjon per etikett, med beskrivelsen sin;
• en blokk per operasjon: metode og URL, sammendrag, gruppemerke, et deprecated-merke der det er aktuelt, en Security-seksjon (skjematype, OAuth 2-flyt, scopes) og en Example payload du kan folde ut;
• tabellene Parameters og Responses (statuskodene er fargelagt);
• Models — en interaktiv graf over skjemaene, som du kan navigere og zoome i;
• Polymorphism — sammensetningene oneOf / anyOf / allOf;
• Enums — enumerasjonene, slått sammen med dem i mappen.

Note

Titlene på disse seksjonene (Models, Enums, Parameters, Responses, Security, Example payload) vises på engelsk i alle språkene til applikasjonen. De gjengis som de er her, slik at du kjenner dem igjen på skjermen.

Opprette en forespørsel fra dokumentasjonen

Hver operasjonsblokk har en + Add-knapp som oppretter en forespørsel som er ferdig satt opp for den operasjonen. Det er den korteste veien når en import har vært delvis, eller når en operasjon nettopp har dukket opp i spesifikasjonen.

Navigere og søke

En innholdsfortegnelse er festet til høyre — seksjonene Overview, Operations, Models, Enums — og kan foldes sammen og endres i størrelse. Å klikke på en modell ruller ned til grafen og sentrerer den tilsvarende noden.

Hurtigtast	Effekt
Ctrl+F / Cmd+F	Åpner søket i dokumentasjonen
F3 / Enter	Neste treff
Shift+F3 / Shift+Enter	Forrige treff
Esc	Lukker søket

En teller viser hvor du er i treffene.

Oppdatere dokumentasjonen

En spesifikasjon utvikler seg. Restorm kan hente kilden og bruke deltaet — dokumentasjon og forespørsler — uten å overskrive arbeidet ditt.

Bare for importer via URL

Resynkronisering er bare tilgjengelig hvis mappen ble importert fra en URL. En import fra en fil eller ved innliming lagrer ingen kilde, og oppdateringsknappen vises ikke: startunderfanen viser da «Denne mappen ble ikke opprettet fra en importerbar kilde.»

Denne URL-en kan ikke endres i etterkant i grensesnittet. Gjør en ny import hvis du vil bytte kilde.

Hvor knappen ligger

To inngangspunkter, likeverdige:

1. startunderfanen i miljømappen, seksjonen Oppdateringer av API-spec — den viser URL, Sist importert og Sist sjekket, og har knappen Oppdater;
2. høyreklikk på mappen i sidefeltet → Oppdater.

Det finnes ingen automatisk sjekk

Restorm overvåker ikke spesifikasjonene dine i bakgrunnen og varsler deg ikke om at en ny versjon er tilgjengelig. Sjekken utløses alltid av deg.

Hva som skjer

1. Et vindu «Oppdaterer API-spec …» vises mens kilden hentes. {{variables}} i URL-en og i headerne løses opp, og autentiseringsruten som er koblet til, kjøres først.
2. Restorm sammenligner et fingeravtrykk av kilden som ble hentet, med det som ble lagret ved forrige import.
3. Ingenting har endret seg → «API-spec er oppdatert.», og da er du ferdig.
4. Noe har endret seg (eller hentingen feilet) → resynkroniseringsveiviseren åpnes.

Veiviseren

• Kilde-URL-en vises som skrivebeskyttet.
• En brikke lar deg koble til, endre eller koble fra en autentiseringsrute, og en undermeny Custom headers lar deg legge til faste headere som spilles av ved hver oppdatering.
• To forhåndsvisningsfaner:
  • Routes — treet over operasjonene som ble funnet i den nye versjonen, med filter og utvalg. Operasjonene som allerede finnes i mappen din, er låst og alltid avkrysset; du velger bare hvilke av de nye som skal legges til;
  • Documentation — dokumentasjonen for den nye versjonen, skrivebeskyttet, før du bekrefter.
• Bekreftelsesknappen viser antallet nye operasjoner som er valgt, for eksempel Apply update (3).

Note

Veiviseren vises i dag på engelsk uansett hvilket språk applikasjonen står på («Refresh from source», «Apply update», fanene «Routes» og «Documentation»). De engelske betegnelsene gjengis derfor som de er her.

Hva som endres, og hva som ikke endres

Det er hovedpoenget: spesifikasjonen har siste ord om det den beskriver, du har siste ord om resten.

Element	Oppførsel
Navnet på en forespørsel	Aldri endret
Metode og URL	Aldri endret
Eksisterende parametere, headere og stiparametere	Beholdes som de er — verdi, beskrivelse, aktivering
Parametere som spesifikasjonen legger til	Legges til, med standardverdien fra spesifikasjonen eller tomme
Parametere som er fjernet fra spesifikasjonen	Beholdes på forespørselen
Ny operasjon	Legges til der en helt ny import ville ha plassert den (etikettmappen inkludert)
Operasjon som spesifikasjonen merker som utdatert	Markeres; den vises nedtonet i treet
Operasjon som er forsvunnet fra spesifikasjonen	Markeres som fjernet; den vises gjennomstreket i treet, er fortsatt kjørbar og slettes aldri
API-dokumentasjon og enumerasjoner	Erstattes i sin helhet av den nye versjonen — det er dette som friskner opp Docs-fanen

Ingenting slettes noen gang fra treet ditt: en operasjon som forsvinner fra kilden, blir markert, ikke fjernet.

Hvis kilden krever autentisering

Et 401- eller 403-svar åpner veiviseren med feilmeldingen vist som den er (for eksempel HTTP 401: Unauthorized). Koble til en autentiseringsrute eller legg til faste headere, så kjøres forhåndsvisningen på nytt.

Formater som kan synkroniseres på nytt

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

For alle andre lager en ny import et nytt tre. Den fullstendige listen finnes i Oppdatere fra kilden.