Konfiguracja

Wpis ten jest swojego rodzaju rozszerzeniem poprzedniego artykułu: ASP.NET WebAPI: Swagger . Zawarte są w nim wszystkie szczegóły, dokładny opis oraz sporo zrzutów ekranów. W tym wpisie skupimy się na .NET Core WebAPI - same konkrety. Będziemy potrzebować nieco innej paczki a sam proces konfiguracji odbywa się w pliku konfiguracyjnym projektu Startup.cs.

Pierwszym krokiem jest pobranie odpowiedniej paczki: Nuget Package Manager

Po poprawnej instalacji przechodzimy do wspomnianego powyżej pliku konfiguracyjnego i dodajemy wpis związany z nowo pobraną paczką:

public void ConfigureServices(IServiceCollection services)
{
	services.AddMvc();
	services.AddSwaggerGen(c =>
	{
		c.SwaggerDoc("v1", new Info
		{
			Version = "v1",
			Title = "Moje API .NET Core",
			Description = "Przykładowy opis",
			TermsOfService = "None",
			Contact = new Contact() { Name = "Strona główna - plukasiewicz.net", 
									  Email = "Zakładka: kontakt", 
									  Url = "https://www.plukasiewicz.net/" }
		});
	});
}

Nasze WebAPI jest już w stanie używać usługi Swagger. Musimy jednak włączyć jeszcze interfejs użytkownika:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
	if (env.IsDevelopment())
	{
		app.UseDeveloperExceptionPage();
	}
	app.UseMvc();
	app.UseSwagger();
	app.UseSwaggerUI(c =>
	{
		c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
	});
}

Powyżej przeprowadziliśmy minimalną konfigurację niezbędną do pracy. W projekcie .NET Framework używaliśmy do tego pliku konfiguracyjnego SwaggerConfig.cs. W przypadku projektu .NET Core etap ten wygląda nieco inaczej.

Ostatnią zmianą poprawiającą komfort pracy jest ustawienie odpowiedniego adresu URL podczas uruchamiania aplikacji. Aby ustawić interfejs użytkownika Swagger przechodzimy do właściwości projeku a następnie wybieramy zakładkę Debug. Zaznaczamy oraz uzupełniamy wartość dla Launch browser: Launch Browser Option

W celu prezentacji użyłem kontrolera z poprzedniego artykułu wraz z niewielkimi zmianami wymaganymi przez .NET Core: Swagger UI Możecie oczywiście zobaczyć pewne zmiany graficzne w stosunku do poprzedniego artykułu. Najważniejsze, że zmianie nie uległo zachowanie. Po kliknięciu przycisku "Try it out!" zostaną wyświetlone wszystkie szczegóły dotyczące metody a samo wywołanie następuje po wciśnięciu przycisku "Execute".

Swagger: komentarze

Domyślna konfiguracja nie wyświetla komentarzy. Istnieje jednak prosty sposób na dodanie ich do naszej dokumentacji. W pierwszym kroku musimy się upewnić, że wszystkie komentarze w projekcie są zapisywane do pliku XML. Plik ten zostanie użyty przez Swagger do wyświetlenia komentarzy w interfejsie użytkownika.

Przechodzimy do właściwości projektu, a następnie, w zakładce Build zaznaczamy opcję XML documentation file: ZML Documentation File

Następnie dodajemy odpowiednią opcję konfiguracyjną:

c.IncludeXmlComments(GetXmlCommentsPath());
Należy również dodać implementację metody GetXmlCommentsPath() - określa lokalizację wygenerowanego pliku XML:
private string GetXmlCommentsPath()
{
	string webRootPath = _hostingEnvironment.WebRootPath;
	string contentRootPath = _hostingEnvironment.ContentRootPath;

	return System.IO.Path.Combine(contentRootPath, "SwaggerUI-DotNetCore.xml");
}
Użycie prywatnej zmiennej _hostingEnvironment jest możliwe poprzez wykorzystanie mechanizmu wstrzykiwania zależności:
public class Startup
{
	private readonly IHostingEnvironment _hostingEnvironment;
	public Startup(IConfiguration configuration, IHostingEnvironment hostingEnvironment)
	{
		Configuration = configuration;
		_hostingEnvironment = hostingEnvironment;	
	}

	// Dalsza cześć kodu

}
Kolejne uruchomienie powoduje dodanie wszelkich komentarzy do naszej dokumentacji: Swagger UI

Swagger: typ wyliczeniowy

W ostatnim kroku do sekcji konfiguracyjnej dodamy wpis dotyczący wyświetlania wartości tekstowych typów wyliczeniowych zamiast ich numerycznej reprezentacji. Na powyższym zrzucie ekranu możecie zobaczyć, że engineType (rodzaj silnika) to wartości 0 oraz 1 – niezbyt opisowe, prawda?

Do sekcji konfiguracyjnej

services.AddSwaggerGen(c =>
{

	// Kod właściwy

});
Dodajemy kolejną opcję:
c.DescribeAllEnumsAsStrings();
Możecie teraz zobaczyć tekstową reprezentację typu wyliczeniowego: Swagger UI

Podsumowanie

Swagger to świetne narzędzie do testowania interfejsów API. Po odpowiedniej konfiguracji tworzy prosty ale niezwykle czytelny interfejs użytkownika. Pozwala na wyświetlenie wszystkich dostępnych metod, prezentuje szczegóły dotyczące wskazanej metody oraz pozwala na zwrócenie odpowiedzi z API. Integracja z .NET Core jest również prosta i wymaga minimalnego wysiłku. Swagger pozwala również na dostosowanie do własnych potrzeb.