OpenAPI / Swagger importeren

Dit is de meest volledige import van Restorm. Er worden drie versies herkend: Swagger 2.0, OpenAPI 3.0 en OpenAPI 3.1.

Importeren

Bestand ▸ Importeren (Ctrl+I), en daarna een bestand swagger.json / openapi.json, of direct de URL van de specificatie.

Antwoordt de URL met 401 of 403, dan biedt Restorm u aan een authenticatie te koppelen en het opnieuw te proberen, zonder het importdialoogvenster te verlaten.

Wat er wordt geïmporteerd

Element uit de specificatie	Wat Restorm daarmee doet
servers (of host + basePath + schemes)	De basis-URL van de omgeving, met de servervariabelen opgelost
tags	Eén map per label, plus een map Other voor de rest
Elke operatie	Een HTTP-verzoek, inclusief methode en pad
Parameters	Pad-, query- en headerparameters, getypeerd (tekenreeks, getal, datum/tijd, enumeratie, geheim…)
requestBody	De body, in het bijbehorende contenttype
examples	De body vooraf gevuld met het meegeleverde voorbeeld
components / definitions	De API-documentatie: modellen, beschrijvingen
enum	Enumeraties die als waardetype herbruikbaar zijn
Responsen	Gedocumenteerd per contenttype

De $ref-verwijzingen worden opgelost, ook door de componenten heen.

De regel components / definitions verdient de nadruk: de import blijft niet bij de verzoeken, maar bewaart de volledige documentatie van de API — beschrijvingen, modellen, beveiligingsschema’s, voorbeelden, enumeraties. U bekijkt die in het tabblad Docs van de omgevingsmap die uit de import komt, en ook in dat van elk verzoek, en zij synchroniseert opnieuw vanaf de bron. Zie Toegang tot en bijwerken van de documentatie van een geïmporteerde API.

Beveiliging

De gedeclareerde beveiligingsschema’s worden omgezet in voorgeschakelde headers of parameters, met de bijbehorende omgevingsvariabele die voor u wordt aangemaakt:

Schema	Wat Restorm neerzet
apiKey in een header of in de query	Een paar dat naar het schema is genoemd, met waarde {{<schema>}}
http + basic	Authorization: Basic {{<schema>_credentials}}
http + bearer, oauth2, openIdConnect	Authorization: Bearer {{<schema>_token}}

U hoeft alleen nog de variabele in te vullen — of haar te vervangen door een authenticatieroute om van de automatische vernieuwing te profiteren.

Bekende beperkingen

apiKey-waarden die via een cookie worden meegestuurd, worden niet voorgeschakeld (OpenAPI 3). Een beveiligingsschema waarnaar wordt verwezen maar dat niet is gedeclareerd, wordt stil overgeslagen.

Bijwerken

OpenAPI en Swagger horen bij de formaten die opnieuw te synchroniseren zijn: de knop Vernieuwen van de map haalt de bron op en Restorm past het verschil toe — nieuwe operaties worden toegevoegd, verdwenen operaties worden als verouderd gemarkeerd in plaats van verwijderd, en uw wijzigingen blijven behouden. Zie Bijwerken vanaf de bron.