Swagger voor webAPI's

In de moderne webontwikkelingssfeer spelen API's een cruciale rol bij de gegevensoverdracht. Er is echter geen industriestandaard voor het ontwerpen en documenteren van API's. Om een API te begrijpen en te gebruiken, moeten ze op een gebruiksvriendelijke manier toegankelijk zijn. Ze moeten ook duidelijke documentatie hebben over de functionaliteit van de endpoints van de API, waardoor ontwikkelaars en testers deze gemakkelijker kunnen begrijpen. Gelukkig is er een specificatie genaamd Swagger die helpt bij het toegankelijk maken en begrijpen van API's. Dit bericht zal vragen beantwoorden zoals wat Swagger is, waarom het te gebruiken, en ook kijken naar een praktische implementatie van Swagger.

Wat is Swagger?

Swagger, ook bekend als de OpenAPI-specificatie, is een taalonafhankelijk raamwerk dat wordt gebruikt om RESTful API's te beschrijven. Door de structuur van de API te lezen, biedt Swagger gebruiksvriendelijke en interactieve API-documentatie.

Swagger biedt de structuur van een API en de bijbehorende metadata die zowel voor mensen als machines leesbaar is. Het biedt informatie over een lijst van alle operaties die de API ondersteunt, de parameters die door een endpoint worden verwacht, en de waarde die het teruggeeft.

Waarom Swagger gebruiken?

Gebruiksvriendelijk

Swagger wordt geleverd met een gebruiksvriendelijk scherm dat de gehele structuur van de API beschrijft. Het stelt niet alleen ontwikkelaars in staat, maar ook productmanagers, belanghebbenden en testers om een goed begrip van het ontwerp van de API te hebben.

Mens- en machineleesbaar

Het is niet alleen vriendelijk voor gebruikers, het is ook machineleesbaar en helpt bij het automatiseren van API-afhankelijke processen.

Helpt bij het oplossen van API-problemen

Met behulp van de Swagger UI kunnen ontwikkelaars en testers de vereiste endpoints aanroepen met de juiste invoerparameters voor het debuggen en oplossen van problemen in de API.

Helpt bij het bouwen van design-first API

Swagger biedt een blauwdruk van de API die kan worden gebruikt voor de top-down benadering. Met andere woorden, een design-first benadering, waarbij de endpoints en de vereiste parameters worden gedefinieerd voordat zelfs maar de daadwerkelijke bedrijfslogica is geschreven.

Gebruikersbasis

Swagger wordt ondersteund door grote bedrijven en er zijn veel mensen in de huidige wereld die kunnen helpen bij problemen of kwesties die ontwikkelaars tegenkomen tijdens de implementatie ervan.

Helpt bij testen en kwaliteitsborging

De definitie van Swagger is machineleesbaar en wordt een enkele bron van waarheid voor de API. Dit helpt bij het testen van elke operatie van het endpoint met de juiste invoer. Ook kunnen API-definities worden geïmporteerd in tools zoals Postman die kunnen worden gebruikt voor handmatig testen.

Swagger-tools voor API's

Praktische implementatie van Swagger

In deze sectie bekijken we stap voor stap hoe je Swagger implementeert voor een op .NET Core gebaseerde Web API.

Stap 1.

Maak een nieuw project aan met een ASP .NET Core webapplicatie en geef het een naam.

Stap 2.

Kies ‘API’ als het type webapplicatie en klik op de knop ‘Create’. Zodra het project is aangemaakt, zou de oplossing er als volgt uitzien. 

Stap 3.

Open het NuGet Package Manager-venster en installeer de onderstaande pakketten in het project. 

Swashbuckle.AspNetCore

Swashbuckle.AspNetCore.Swagger

Swashbuckle.AspNetCore.SwaggerUI

Stap 4. 

Na het installeren van de pakketten, open je het bestand Startup.cs, zoek je de methode 'ConfigureServices' en voeg je de onderstaande regel toe. 

services.AddSwaggerGen();

Stap 5.

Zoek in hetzelfde bestand startup.cs de methode 'Configure' en voeg de onderstaande regels toe. 

app.UseSwagger(c =>

{

       c.SwaggerEndpoint(“/Swagger/v1/Swagger.json”,”My API v1”);

});

Het API-project wordt standaard geleverd met de WeatherForecastController. Deze heeft een Get-methode met enkele weergegevens erin. Laten we proberen deze te benaderen met behulp van Swagger. 

Stap 6.

Debug het API-project lokaal. Het project wordt geopend in een browser. Vanaf de basis-URL van de applicatie, bijvoorbeeld  - https://localhost:44377 add /Swagger/index.html

https://localhost:44377/Swagger/index.html

Na het uitvoeren van de bovenstaande URL, wordt Swagger voor de API weergegeven in de browser met het enige beschikbare eindpunt erin. 

Stap 7.

We kunnen proberen het eindpunt uit te voeren vanuit Swagger door op het eindpunt te klikken en de optie ‘Probeer het uit’ te selecteren. Aangezien dit eindpunt geen invoergegevens vereist, kun je rechtstreeks op de knop ‘Uitvoeren’ klikken. 

Na uitvoering verschijnen de gegevens samen met de response statuscode. 

Afronding

Swagger is een van de krachtigste en nuttigste tools in de wereld van API's. De functies van Swagger maken het voor ontwikkelaars gemakkelijker om het documentatieproces van API's te automatiseren. Dus ga ervoor en probeer het uit in je volgende web-API.