Open API Specification (OAS)
Inleiding
Microsoft heeft in november 2024 .Net 9 uitgebracht. Eén van de vele wijzigingen in .Net 9 is dat nu meer de nadruk wordt gelegd op het doen genereren van OpenAPI-documenten.
Een andere wijziging is dat Swagger niet meer automatisch deel uitmaakt van de tools die je voor het bouwen van je Web API kunt gebruiken.
We gaan in deze post nader in op deze ontwikkelingen waarbij we het één en ander toelichten aan de hand van een ASP .NET 9 Web API-project. Als IDE gebruiken we Visual Studio 2022 (versie 17.12.0).
Web API-project
We creëren met Visual Studio een nieuw project en we gebruiken de ASP.NET Core Web API-template:
We gebruiken .NET 9 voor de Web API :
OpenAPI support is één van de opties die je kan aanvinken bij de creatie van je Web API-project.
Open API-documenten
Je zal het één en ander moeten weten over een Web API voor het doen “consumeren” van de Web API. Hoe deze aan te roepen, wat is nodig aan input en wat krijg je terug aan output? Al deze info kan vastgelegd worden in een zogenaamd open API specificatie-document.
Microsoft heeft in .Net 9 meer op OpenAPI-documenten ingezet en deze kunnen vanuit de code gegenereerd worden middels de Microsoft.AspNetCore.OpenApi-package.
We hadden bij de aanmaak van onze Web API-project gekozen voor OpenAPI support en deze package zal je dan ook terugvinden in je Web API-project:
De ASP.NET Core Web API-template bevat out-of-the-box een WeatherForecast-endpoint dat vijf WeatherForecast-objecten retourneert. We gaan het één en ander verder bekijken aan de hand van die endpoint.
OpenAPI
We moeten het volgende doen om van ons Web API-project wat te kunnen zien. Open de launchSettings.json:
En ken aan eigenschap launchBrowser de waarde true toe zodat bij het opstarten van de Web API de browser wordt geopend waarin we de open API specificatie-document kunnen bekijken:
In ASP .NET wordt een host geactiveerd bij het opstarten van een applicatie (meer over de host in deze post). De host zet dingen klaar die nodig zijn voor het doen draaien van de applicatie en we willen in dit geval de open API specificatie-document zien dat uit de code gegenereerd wordt door de Microsoft.AspNetCore.OpenApi-package. Activeer in de host als volgt de package:
En we hebben nu een openapi-endpoint waarbij we met deze url:
http://localhost:<poortnummer>/openapi/v1.json
de gegenereerde API specificatie-document krijgen te zien over de WeatherForecast-endpoint die out-of-the-box meegeleverd wordt met de ASP.NET Core Web API-template:
Erg leuk zo’n API specificatie-document, maar we willen een UI waarmee we onze Web API willen bekijken en willen testen. In de vorige versies van .Net hadden we daar Swagger voor, maar die is er zo te zien niet meer?
Swagger
Swagger maakte deel uit van de ASP.NET Core Web API-template. Microsoft heeft echter besloten dat Swagger met ingang van .Net 9 niet meer met de project templates wordt meegeleverd wat ze in dit schrijven hebben aangekondigd. Dit omdat volgens het ASP.NET Core team Swagger niet meer actief door de community owners wordt onderhouden en omdat Microsoft meer wil inzetten op OpenAPI-documentatie zonder afhankelijk te zijn van externe partijen zoals Swashbuckle.
Het besluit heeft als gevolg dat je nu zelf wat moet installeren als je een UI wilt hebben voor het kunnen bekijken en het kunnen testen van je Web API. Er zijn meerdere tools op de markt en Swagger kan je ook nog steeds gebruiken. Installeer voor Swagger de Swashbuckle.AspNetCore.SwaggerUI-package:
En activeer Swagger als volgt in de host:
Je ziet dat Swagger gebruik maakt van de openapi-endpoint welke gefaciliteerd wordt door de Microsoft.AspNetCore.OpenApi-package. En met deze url krijgen we weer het wel bekende Swagger-scherm te zien:
http://localhost:<poortnummer>/swagger/index.html
Scalar
Er zijn naast Swagger tal van andere tools waarmee je een UI krijgt voor het kunnen bekijken en het kunnen testen van je Web API. Scalar is een tool dat veel door de developer community wordt genoemd en we besteden dan ook aandacht aan deze tool als mogelijke vervanger van Swagger. Installeer voor Scalar de Scalar.AspNetCore-package:
En activeer Scalar als volgt in de host:
En we krijgen met deze url Scalar:
https://localhost:<poortnummer>/scalar/v1
Andere versie Web API
We zijn tot dusver uitgegaan van een versie 1 voor de Web API. Het kan best zijn dat je je Web API een hogere versie nummer wilt geven. Geef in het geval van een versie 2 dit op bij de host:
builder.Services.AddControllers();
// Learn more about onfiguring OpenAPI
// at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi("v2")
Wat weer als gevolg heeft dat je het versie nummer in al je urls moet aanpassen om je hogere versie van je Web API te kunnen zien:
http://localhost:<poortnummer>/openapi/v2.json
options.SwaggerEndpoint("/openapi/v2.json","v2");
http://localhost:<poortnummer>/scalar/v2
Slot
Misschien was het even schrikken met .Net 9, maar Swagger zit niet meer in de Visual Studio project templates. Redenen voor Microsoft voor het weglaten van Swagger zijn het kunnen inzetten op OpenAPI-documentatie zonder afhankelijk te zijn van externe partijen en het feit dat Swagger niet meer door de community owners wordt onderhouden.
In deze post hebben we eerst aandacht besteed aan Microsoft’s OpenAPI support middels de Microsoft.AspNetCore.OpenApi-package. Swagger zit sinds .Net 9 niet meer in de project templates, maar je kunt Swagger nog steeds gebruiken en dat is het volgende onderwerp waar we in deze post aandacht aan hebben besteed. Scalar is een tool dat veel door de developer community wordt genoemd en we hebben als laatste onderwerp in deze post dan ook aandacht besteed aan Scalar en hoe deze geactiveerd kan worden in je Web API-project.
Er zijn naast Swagger en Scalar tal van andere tools die een User Interface leveren waarmee je je Web API kunt bekijken en kunt testen. We hadden daar out-of-the-box Swagger voor, maar Microsoft heeft dit met .Net 9 niet meer voor je ingevuld en het is nu aan de ontwikkelaar welke tool ervoor te gebruiken.
Hopelijk ben je met deze post weer wat wijzer geworden en ik hoop je weer terug te zien in één van mijn volgende blog posts. Klik op de Home-button om te zien wat ik nog meer geschreven heb…