Ga naar inhoud
Restorm Restorm-documentatie

Problemen in een geïmporteerde API opsporen

Wanneer u een API importeert (OpenAPI, Swagger en de andere ondersteunde formaten), bewaart Restorm de gestructureerde documentatie van de API op de bijbehorende omgevingsmap. Direct na de import — en telkens wanneer u het bestand opnieuw opent — projecteert Restorm die documentatie stilletjes in een ontwerp en voert het dezelfde validatie uit als de API-designer, volledig op de achtergrond. Het blokkeert de import nooit en raakt nooit aan waar u mee bezig bent.

Vindt het niets, dan ziet u niets. Vindt het structurele problemen, dan wijst het u er op twee plaatsen op.

De “!” in de zijbalk

Section titled “De “!” in de zijbalk”

De omgevingsmap die de gemarkeerde API bevat, toont een kleine “!” rechts van de rij. Het is het signaal in één oogopslag dat het ontwerp van deze API iets bevat dat aandacht verdient — en het verdwijnt vanzelf zodra de API weer schoon is (na een herimport of een API-update die het corrigeert).

Het tabblad “Problemen”

Section titled “Het tabblad “Problemen””

Open de omgevingsmap en er verschijnt een tabblad Problemen. Het tabblad verschijnt alleen wanneer er problemen zijn gedetecteerd — een schone API toont het nooit.

Het tabblad Problemen van de omgevingsmap van een geïmporteerde API: een waarschuwing, daarna de problemen gegroepeerd per type — “Meerdere routes beantwoorden dezelfde methode en hetzelfde pad”, “Sommige routes declareren geen respons”, “Sommige routes bevinden zich op een pad dat de ontwerpserver reserveert” — elk met de exacte routes die het betreft, waarvan er één is uitgeklapt om de documentatie van die route te tonen

Problemen worden gegroepeerd per type, zodat twintig dubbele routes te lezen zijn als één regel met een telling in plaats van twintig afzonderlijke vermeldingen. Onder elk type somt Restorm de exacte betrokken entiteiten op — een route toont zijn HTTP-werkwoord en het werkelijke pad, en klapt uit tot de documentatie van die route zodat u kunt zien wat deze declareert zonder het tabblad te verlaten.

De controles weerspiegelen die van de API-designer, dus de soorten problemen die u kunt zien, omvatten:

  • dubbele routes — twee routes die dezelfde methode en hetzelfde pad beantwoorden;
  • ontbrekende responsen — een route die helemaal geen respons declareert;
  • gereserveerde paden — een route die zich bevindt op een pad dat de Mock Server reserveert (/swagger.json, /graphql, …), en die nooit zou antwoorden;
  • beperkingsproblemen — een ongeldig patroon, of een minimum dat hoger is dan het maximum.

De lijst is alleen-lezen: hij vertelt u wat u moet corrigeren, en u corrigeert het bij de bron (importeer een gecorrigeerde specificatie opnieuw, of bewerk de API). Hij wordt opnieuw berekend bij de gebeurtenissen die een API wijzigen — het openen van een bestand, een import, een API-update — niet bij elke toetsaanslag.