19.

Swagger och loggning

Vad vi går igenom
 Dokumentera ett Web api

 Vad är Swagger och Open API?

 Swashbuckle

 Loggning i ett Web api

Dokumentera ett Web Api
 En viktig del i att bygga ett Web api är att skapa
dokumentation som gör att det är enkelt att se hur api:et
fungerar och är tänkt att användas.

 Speciellt viktigt om det handlar om ett api som skall

publiceras externt och användas.

 Typiska saker som är viktiga att dokumentera är vilka

typer av anrop som finns. Vilka inparametrar skall/kan
skickas med. Vad kommer att returneras samt hur ser
authentication ut för lösningen.
Dokumentera ett Web Api

 Att skriva sådan dokumentation kan vara tidskrävande

och därför används ofta ett verktyg för att underlätta.

 Det finns ett antal sådana verktyg på marknaden som

fungerar på olika sätt. Vi skall nu titta på ett av dessa
verktyg.
Vad är Swagger ?

 Ett standard för att skapa dokumentation i ett Web api

projekt. Första versionen kom 2011.

 Följer Open API som är en specifikation som tagits fram

för att beskriva REST API:er.

 Kan användas i olika typer av projekt inte bara ASP.NET

Web api.

 Använder JSON för att presentera information.

Swashbuckle

 Swashbuckle är ett C# klassbibliotek med klasser och

metoder. Ett verktyg som kan läggas till i ett ASP.NET
Web api projekt för att hantera dokumentation. När detta
installeras kommer Swagger med.

 Funkar som en Swagger generator och används för att

skapa Swagger dokument.

 Innehåller funktionalitet som automatiskt skapar upp

dokumentation i projektet.
Swashbuckle
Swashbuckle består av 3 komponenter (assemblies) som
kommer med när det installeras.

Swagger: Består av en objektmodell med klasser och

middleware för att sätta upp det i ett projekt

SwaggerGen: Genererar upp json filer med dokumentation

Swagger UI: Ett sätt att visa Swagger dokumentationen

på ett enkelt och användarvänligt sätt utifrån
JSON-filer . Går även att testa anrop via
detta UI.
Sätta upp Swagger
Först måste ett Nuget paket installeras. Då laddas alla 3
komponenterna ned. Det heter

Swashbuckle.AspNetCore.

Därefter sätts en service upp i ConfigureServices i Startup.

builder.services.AddControllers();
builder.services.AddSwaggerGen();
Sätta upp Swagger
Även Configure i Startup måste sättas upp. När
applikationen byggs genereras en JSON fil som
dokumenterar vilka controllers och metoder som finns i
API:et. Denna fil används sedan av Swagger UI för att
visa upp dokumentationen för användaren.

app.UseRouting(); Swagger UI utgår från

denna fil
app.UseSwagger();
app.UseSwaggerUI(endpoint =>
{
endpoint.SwaggerEndpoint("/swagger/v1/swagger.json", "My API dok");
});
Loggning

 Kan sättas upp på många sätt. Det finns inbyggt i NET

men går även att använda andra providers.

 Vanligt är att man skriver till systemloggen på servern.

 Det inbyggda sättet fungerar i de flesta fall bra . Det finns

tillgängligt via Microsoft.Extensions.Logging. Det är detta
sätt som vi kommer att titta på och använda under
kursen.
Länkar

https://en.wikipedia.org/wiki/Swagger_(software)

https://www.c-sharpcorner.com/article/swagger-in-dotnet-core/

https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-
with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio

https://crosscuttingconcerns.com/swashbuckle-swagger-asp-net-core

https://www.ezzylearning.net/tutorial/a-step-by-step-guide-to-logging-
in-asp-net-core-5
Länkar - videos

https://www.youtube.com/watch?v=jH8hNdVNCN0

https://www.youtube.com/watch?v=TlytBx3-k-k
DEMO