Werken met de Swagger UI

De dynamische API genereert automatisch een Swagger UI interface die je kunt gebruiken om je API te verkennen en te testen. Deze interface biedt documentatie van alle endpoints en stelt je in staat om verzoeken te maken zonder eerst de code te hoeven schrijven.

Toegang tot Swagger UI

Je kunt de Swagger UI vinden op de volgende URL*:

https://novi-backend-api-wgsgz.ondigitalocean.app/swagger-ui?projectId=ed30b6ec-f22a-4fa0-aceb-7aa8504e3e98

*Vervang de projectId-parameter met je eigen project GUID.

De Swagger UI interface begrijpen

De Swagger UI-interface bestaat uit verschillende delen:

  1. API-overzicht: Bovenaan zie je algemene informatie over je API en een Authorize knop
  2. Endpoints: Gegroepeerd per collectie en HTTP-methode
  3. Modellen: Onderaan zie je de datamodellen voor jouw collecties

Endpoints verkennen

Elke collectie heeft, afhankelijk van het geleverde JSON-configuratiebestand, meerdere endpoints:

  • GET /{collectie}: Haalt een lijst op van alle items in de collectie
  • GET /{collectie}/{id}: Haalt een specifiek item op, op basis van ID
  • POST /{collectie}: Voegt een nieuw item toe aan de collectie
  • PUT /{collectie}/{id}: Overschrijft alle velden van een bestaand item
  • PATCH /{collectie}/{id}: Werkt een of meerdere velden van een bestaand item bij
  • DELETE /{collectie}/{id}: Verwijdert een bestaand item

Een verzoek uitvoeren in Swagger UI

Wanneer je een verzoek wil doen naar een openbare endpoint, is het meesturen van jouw project ID verplicht. Wanneer je de endpoint uitprobeert in Swagger, wordt deze ID automatisch voor je meegestuurd. In de database-opzet voor de online bibliotheek zijn de endpoints voor het opvragen van boeken, auteurs en genres openbaar (toegankelijk voor zowel ingelogde als niet-ingelogde gebruikers). Het opvragen van alle boeken kun je als volgt uitproberen in de Swagger UI:

  1. Klik op het endpoint dat je wil testen, in ons geval GET api/books
  2. Klik op de knop "Try it out" rechtsboven in het paneel*
  3. Klik vervolgens op de "Execute"-knop om het verzoek uit te voeren
  4. De response (zoals je die in jouw Frontend zult ontvangen) wordt zichtbaar:
    • Je ziet de volledige URL waar het request naartoe gemaakt is en de headers die Swagger voor je heeft meegestuurd ( curl);
    • Je ziet alle boeken (response body) die op dit moment in de database staan en door de API zijn teruggestuurd;
    • Je ziet de response-headers die de API heeft teruggestuurd (hierin vind je bijvoorbeeld de statuscode)

Probeer je een request uit te voeren op een specifiek item met het ID? Dan zal je Swagger eerst een parameter (het ID) moeten meegeven. Indien je een POST, PUT of PATCH-request probeert te maken, dan zal je ook eerst de request body in moeten vullen met de gewenste data.

Beveiligde verzoeken maken in Swagger UI

Wanneer je een verzoek wil doen naar één van de afgeschermde endpoints, is het meesturen van jouw project ID én JWT-token verplicht. Een token verkrijg je normaliter door je als gebruiker in te loggen bij de frontend applicatie. Wanneer je zo'n endpoint wil uitproberen in Swagger, zul je dus eerst een login-verzoek moeten sturen. Daarna krijg je toegang tot afgeschermde endpoints:

  1. Klik op het Authentication POST /api/login endpoint
  2. Klik op de knop "Try it out"
  3. Je krijgt nu de mogelijkheid om de request body (de inloggegevens die worden verstuurd) aan te passen. In de bibliotheekdatabase is al een admin account aanwezig, dus je kunt de volgende waardes invullen:
{
  "email": "[email protected]",
  "password": "admin123"
}
  1. Klik vervolgens op de "Execute"-knop om het verzoek uit te voeren
  2. De response (alle user-gegevens) wordt zichtbaar. Kopieer de waarde die achter token uitgeschreven staat
  3. Scrol helemaal omhoog naar de bovenkant van de documentatie en druk op de "Authorize"-knop
  4. Plak de token (zonder "") in het invoerveld
  5. Klik op "Authorize" en sluit de pop-up. Je hebt Swagger nu als het ware "ingelogd".

Je kunt nu gebruikmaken van alle beveiligde endpoints, omdat Swagger de token nu automatisch voor je mee zal sturen als je andere requests uitprobeert.

Voorbeeld: Een product ophalen

  1. Vind het GET /products/{id} endpoint
  2. Klik op "Try it out"
  3. Voer een geldig product-ID in
  4. Klik op "Execute"
  5. De resultaten worden getoond in het "Response body" veld

Voorbeeld: Een nieuw product toevoegen

  1. Vind het POST /products endpoint
  2. Klik op "Try it out"
  3. Voer een geldig JSON-object in voor het product dat overeen komt met jouw collectie. Let erop dat je alle verplichte velden meestuurt en invult.
    {
  "name": "Nieuw product",
  "description": "Product beschrijving",
  "price": 24.99,
  "categoryId": 1
}
  4. Klik op "Execute"
  5. Controleer het "Response body" om te zien of het product succesvol is toegevoegd

Voorbeeld: Een bestaand product wijzigen met PATCH

  1. Vind het PATCH /products/{id} endpoint
  2. Klik op "Try it out"
  3. Voer een geldig JSON-object in voor het product dat overeen komt met jouw collectie. Stuur alleen de velden mee die je wilt aanpassen.
    {
  "name": "Aangepast nieuw product",
  "price": 19.99
}
  4. Klik op "Execute"
  5. Controleer het "Response body" om te zien of het product succesvol is aangepast

Modellen gebruiken

Onderaan de Swagger UI-pagina vind je de "Schemas" sectie. Hier worden de gegevensstructuren voor je collecties getoond. Dit is handig om te begrijpen welke velden beschikbaar zijn en welke datatypen ze hebben.

Swagger UI is een krachtig hulpmiddel bij het ontwikkelen van je applicatie. Het helpt je de API te begrijpen en snel te testen of alles werkt zoals verwacht.