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:

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:

W celu prezentacji użyłem kontrolera z poprzedniego artykułu wraz z niewielkimi zmianami wymaganymi przez .NET Core: 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".

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:

Następnie dodajemy odpowiednią opcję konfiguracyjną:

c.IncludeXmlComments(GetXmlCommentsPath());

private string GetXmlCommentsPath()
{
	string webRootPath = _hostingEnvironment.WebRootPath;
	string contentRootPath = _hostingEnvironment.ContentRootPath;

	return System.IO.Path.Combine(contentRootPath, "SwaggerUI-DotNetCore.xml");
}

public class Startup
{
	private readonly IHostingEnvironment _hostingEnvironment;
	public Startup(IConfiguration configuration, IHostingEnvironment hostingEnvironment)
	{
		Configuration = configuration;
		_hostingEnvironment = hostingEnvironment;	
	}

	// Dalsza cześć kodu

}

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

});

c.DescribeAllEnumsAsStrings();

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.