Tuodun API:n dokumentaation käyttö ja päivitys

Kun tuot määrityksen, Restorm ei luo pelkkiä pyyntöjä: se säilyttää API:n dokumentaation — kuvaukset, mallit, tietoturvaskeemat, esimerkit ja luettelotyypit — ja liittää sen tuonnin luomaan muuttujakansioon.

Dokumentaation avaaminen

Muuttujakansion Docs-välilehti

Tämä on päänäkymä. Avaa tuonnista syntynyt muuttujakansio: sen alavälilehtipalkissa on välilehti Docs välilehtien Ympäristöt, Mukautetut muuttujat ja Muistiinpanot vieressä.

Välilehti näkyy vain, jos kansio on peräisin tuonnista — käsin luodulla muuttujakansiolla ei ole dokumentaatiota näytettäväksi.

Muut reitit

Mistä	Mitä saat
Pyynnön Docs-välilehti	Vain kyseisen operaation dokumentaatio — ilman sisällysluetteloa ja yleistietolohkoa. Se näkyy vain, jos operaatio löytyy määrityksestä
Tavallisen kansion Docs-välilehti	Dokumentaatio rajattuna kansion sisältämiin operaatioihin
Muuttujakansion aloitusalavälilehti	Kortti Näytä dokumentaatio — ”Selaa API:n dokumentaatiota, malleja ja päätepisteitä”
Aloitusnäyttö (API-kortti)	Pikalinkki Dokumentaatio
Otsikkopalkin hakukone	Dokumentaation esikatselu, kun tulosta osoitetaan hiirellä

Mitä näkymä sisältää

Ylhäältä alas:

• API:n otsikko ja sen kuvaus;
• tietolohko: Version, Source format (linkillä lähde-URL:iin), Server (skeemat, isäntä, peruspolku), Contact, License, Terms of service, External docs;
• osio kutakin tunnistetta kohti kuvauksineen;
• lohko kutakin operaatiota kohti: metodi ja URL, tiivistelmä, ryhmämerkintä, tarvittaessa merkki deprecated, osio Security (skeeman tyyppi, OAuth 2 -virrat, laajuudet) ja taitettava Example payload;
• taulukot Parameters ja Responses (tilakoodit on väritetty);
• Models — skeemojen vuorovaikutteinen graafi, jossa voi navigoida ja zoomata;
• Polymorphism — koosteet oneOf / anyOf / allOf;
• Enums — luettelotyypit, yhdistettynä kansion omiin.

Note

Näiden osioiden nimet (Models, Enums, Parameters, Responses, Security, Example payload) näytetään englanniksi kaikilla sovelluksen kielillä. Ne on toistettu tässä sellaisenaan, jotta löydät ne näytöltä.

Pyynnön luominen dokumentaatiosta

Jokaisessa operaatiolohkossa on painike + Add, joka luo kyseiselle operaatiolle esimääritetyn pyynnön. Se on lyhin reitti silloin, kun tuonti on jäänyt osittaiseksi tai kun operaatio on juuri ilmestynyt määritykseen.

Navigointi ja haku

Sisällysluettelo on ankkuroitu oikealle — osiot Overview, Operations, Models, Enums — ja se on taitettavissa ja kokoa muutettavissa. Mallin napsauttaminen vierittää graafiin ja keskittää vastaavan solmun.

Pikanäppäin	Vaikutus
Ctrl+F / Cmd+F	Avaa haun dokumentaatiosta
F3 / Enter	Seuraava osuma
Shift+F3 / Shift+Enter	Edellinen osuma
Esc	Sulkee haun

Laskuri kertoo sijainnin tuloksissa.

Dokumentaation päivittäminen

Määritys kehittyy. Restorm osaa hakea lähteen uudelleen ja soveltaa erotuksen — sekä dokumentaation että pyynnöt — ylikirjoittamatta työtäsi.

Vain URL-osoitteesta tehdyille tuonneille

Uudelleensynkronointi on käytettävissä vain, jos kansio on tuotu URL-osoitteesta. Tiedostosta tai liittämällä tehty tuonti ei tallenna lähdettä, eikä päivityspainike näy: aloitusalavälilehti näyttää tällöin tekstin ”Tätä kansiota ei ole luotu tuotavasta lähteestä.”

Tätä URL-osoitetta ei voi muuttaa jälkikäteen käyttöliittymässä. Vaihtaaksesi lähteen tee tuonti uudelleen.

Missä painike on

Kaksi keskenään vastaavaa reittiä:

1. muuttujakansion aloitusalavälilehti, osio Määrityksen päivitykset — se näyttää arvot URL, Viimeisin tuonti ja Viimeisin tarkistus ja sisältää painikkeen Päivitä;
2. kansion napsauttaminen hiiren oikealla sivupuussa → Päivitä.

Automaattista tarkistusta ei ole

Restorm ei valvo määrityksiäsi taustalla eikä ilmoita, että uusi versio on saatavilla. Tarkistuksen käynnistät aina sinä.

Mitä tapahtuu

1. Haun ajaksi ilmestyy ikkuna ”Määrityksen päivitys…”. URL-osoitteen ja otsakkeiden {{variables}} ratkaistaan, ja liitetty todennusreitti suoritetaan ensin.
2. Restorm vertaa haetun lähteen tiivistettä viimeisimmässä tuonnissa tallennettuun.
3. Mikään ei ole muuttunut → ”API:n määritys on ajan tasalla.”, ja siihen se jää.
4. Jokin on muuttunut (tai haku epäonnistui) → uudelleensynkronoinnin ohjattu toiminto avautuu.

Ohjattu toiminto

• Lähde-URL näytetään vain luettavana.
• Merkintä mahdollistaa todennusreitin liittämisen, muuttamisen tai irrottamisen, ja alavalikko Custom headers kiinteiden otsakkeiden lisäämisen, jotka toistetaan jokaisella päivityksellä.
• Kaksi esikatseluvälilehteä:
  • Routes — uudesta versiosta löytyneiden operaatioiden puu suodattimineen ja valintoineen. Kansiossasi jo olevat operaatiot ovat lukittuina ja aina valittuina; valitset vain, mitkä uusista lisätään;
  • Documentation — uuden version dokumentaatio vain luettavana ennen vahvistusta.
• Vahvistuspainike näyttää valittujen uusien operaatioiden määrän, esimerkiksi Apply update (3).

Note

Ohjattu toiminto näytetään nykyisin englanniksi sovelluksen kielestä riippumatta (”Refresh from source”, ”Apply update”, välilehdet ”Routes” ja ”Documentation”). Englanninkieliset nimet on siis toistettu tässä sellaisinaan.

Mitä muutetaan ja mitä ei

Tämä on olennaista: määritys on auktoriteetti sen suhteen, mitä se kuvaa, ja sinä olet auktoriteetti muun suhteen.

Elementti	Käyttäytyminen
Pyynnön nimi	Ei koskaan muuteta
Metodi ja URL	Ei koskaan muuteta
Olemassa olevat parametrit, otsakkeet ja polkuparametrit	Säilytetään sellaisinaan — arvo, kuvaus ja käytössäolo
Määrityksen lisäämät parametrit	Lisätään määrityksen oletusarvolla tai tyhjinä
Määrityksestä poistetut parametrit	Säilytetään pyynnössä
Uusi operaatio	Lisätään siihen kohtaan, johon uusi tuonti olisi sen sijoittanut (myös tunnistekansioon)
Määrityksen vanhentuneeksi merkitsemä operaatio	Merkitään; se näkyy puussa himmennettynä
Määrityksestä kadonnut operaatio	Merkitään poistetuksi; se näkyy puussa yliviivattuna, pysyy suoritettavana eikä sitä koskaan poisteta
API-dokumentaatio ja luettelotyypit	Korvataan kokonaan uudella versiolla — juuri tämä päivittää Docs-välilehden

Mitään ei koskaan poisteta puustasi: lähteestä kadonnut operaatio merkitään, ei pyyhitä pois.

Jos lähde vaatii todennuksen

Vastaus 401 tai 403 avaa ohjatun toiminnon virheilmoituksineen sellaisenaan (esimerkiksi HTTP 401: Unauthorized). Liitä todennusreitti tai lisää kiinteitä otsakkeita, niin esikatselu käynnistetään uudelleen.

Uudelleen synkronoitavat muodot

Kahdellatoista muodolla on uudelleensynkronointi: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC ja Smithy.

Kaikilla muilla uusi tuonti luo uuden puun. Täydellinen luettelo on sivulla Päivitys lähteestä.