9. 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

@todo base-url

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

/swagger-ui?projectId=ed30b6ec-f22a-4fa0-aceb-7aa8504e3e98

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

De Swagger UI interface begrijpen

@todo afbeelding toevoegen

Swagger UI voorbeeld

De Swagger UI-interface bestaat uit verschillende delen:

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

Endpoints verkennen

Elke collectie heeft 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}: Werkt een bestaand item bij
  • DELETE /{collectie}/{id}: Verwijdert een bestaand item

Een verzoek uitvoeren in Swagger UI

Om een verzoek uit te voeren:

  1. Klik op het endpoint dat je wil testen
  2. Klik op de knop "Try it out" rechtsboven in het paneel
  3. Vul de benodigde parameters in (indien van toepassing)
  4. Voeg eventueel een request body toe (voor POST en PUT)
  5. Klik op "Execute"

Beveiligde verzoeken maken in Swagger UI

Om beveiligde endpoints te testen, moet je jezelf eerst authenticeren met een JWT-token. Deze kun je alleen ophalen als je inlogt met één van de gebruikers die in jouw database staan:

  1. Klik op "Try it out" bij het endpoint om gebruikers in te loggen
  2. Kopieëer de JWT die je terugkrijgt in de response
  3. Klik op de "Authorize" knop bovenaan de pagina
  4. Voer je JWT-token in: Bearer eybed30b6e.askdjalsdw.jkkljsadkasjd
  5. Klik op "Authorize"

Vanaf dat moment worden al je verzoeken met deze token uitgevoerd.

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:
    {
  "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

Modellen gebruiken

Onder aan 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.