ASP.NET Core Web API'da Swagger ile Dökümantasyon Oluşturma
ASP.NET Core ile geliştirmiş olduğumuz Web API’ları kullanarak uygulama geliştirecek olan kişiler için dökümantasyon oldukça önemlidir. API’ın hangi endpointlere sahip olduğu, hangi HTTP metoduyla iletişim kuracağı, endpoint’in almış olduğu parametreler ve body içeriği, API’dan dönecek olan cevabın içeriğinin nasıl olduğu gibi bilgileri vermek uygulama geliştiricilerin işlerini oldukça kolaylaştıracaktır.
ASP.NET Core’da geliştirilmiş olan API’ların dökümantasyonu için kullanabileceğimiz araçlardan birisi Swagger‘dır. Swagger, açık kaynak kodlu bir araçtır. ASP.NET Core özelinde bir araç değildir. 20’nin üzerinde programlama dili veya kütüphane için desteği bulunmaktadır. Swagger’ın kendine has bir JSON dosyası oluşturmaktadır. Oluşturulan bu JSON dosyasından ister Swagger UI‘ı kullanarak isterseniz de kendinizin geliştireceği bir tema ile dökümantasyonunuzu oluşturabilirsiniz.
O zaman örnek uygulamamızı geliştirmeye başlayalım. Öncelikle aşağıdaki terminal komutunu kullanarak yeni bir ASP.NET Core Web API projesi oluşturalım ve kullanmış olduğumuz IDE veya metin editörüyle projemizi açalım.
dotnet new webapi -o aspnetcore-swagger-sample -n AspNetCore.Swagger.Sample
Projemizi oluşturduktan sonra sıra geldi Swagger dosyamızı oluşturacak olan paketi projemize referans olarak eklemeye. Bu işlem için Swashbuckle.AspNetCore paketini kullanacağız. Aşağıdaki komut ile ilgili paketi projemize referans olarak ekleyelim.
dotnet add package Swashbuckle.AspNetCore
İlgili paketimiz ekledikten sonra sırada Swagger ayarlarının yapılması var. Swagger ayalarını yapmak için Startup.cs dosyamızın içeriğini aşağıdaki gibi değiştirelim.
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;
namespace AspNetCore.Swagger.Sample
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Sample Web API", Version = "v1" });
});
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sample Web API v1");
});
app.UseMvc();
}
}
}
AddSwaggerGen metodu ile Swagger JSON dosyamızın oluşturulmasını sağladık. Parametre olarak aldığı Info tipinden bir nesne ile API’ımıza ait çeşitli bilgileri tanımlıyoruz. API’ın adı, sürümü, geliştirici bilgileri v.b. gibi bilgileri burada tanımlıyoruz.
UseSwaggerUI metodu ile Swagger UI’ın dosyalarının oluşturulmasını ve tarayıcı üzerinden erişebilmek için ilgili route tanımlamalarının yapılması sağlanmaktadır.
Şimdi Swagger’ın çalışıp çalışmadığını test edebilmek için projemizi çalıştıralım ve tarayıcıdan http://localhost:5000/swagger adresine girelim. Eğer herhangi bir sorun yoksa aşağıdaki gibi bir ekranla karşılaşacağız.
Dökümantasyonun bir kısmı başarıyla oluştu ancak hala yetersiz bilgiler mevcut. Örneğin endpoint’ler ne işe yarıyor ve HTTP durum kodlarına göre endpoint’den gelecek olan cevabın modeli nedir gibi soruların cevabı bulunmamaktadır.
Şimdi endpoint açıklamalarının gözükmesini sağlayalım. Bu işlem için ValuesController.cs dosyamızı açalım ve aşağıdaki değişiklikleri yapalım.
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
namespace AspNetCore.Swagger.Sample.Controllers
{
[Route("api/[controller]")]
public class ValuesController : Controller
{
///
/// Get all values
///
[HttpGet]
public IEnumerable Get()
{
return new string[] { "value1", "value2" };
}
///
/// Get value by id
///
/// Value id
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
///
/// Create a new value
///
[HttpPost]
public void Post([FromBody] string value)
{
}
///
/// Update value by id
///
/// Value id
/// Value informations
[HttpPut("{id}")]
public void Put(int id, [FromBody] string value)
{
}
///
/// Delete a value by id
///
/// Value id
[HttpDelete("{id}")]
public void Delete(int id)
{
}
}
}
Endpoint açıklamalarını XML Documentation Comments kurallarına göre her action’ın başına ekledik. Bu sayede Swagger dosyası oluşurken ilgili açıklamaların eklenmesini sağladık. Eklemiş olduğumuz açıklamalara ait XML dosyalarının oluşabilmesi için AspNetCore.Swagger.Sample.csproj dosyasını aşağıdaki gibi düzenliyoruz.
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp2.0</TargetFramework>
</PropertyGroup>
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.All" AllowExplicitVersion="true" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="4.0.1" />
</ItemGroup>
</Project>
- ve 9. satırlar arasındaki düzenlemeleri yaparak build işlemi esnasında XML dosyasının oluşmasını sağladık.
Son aşama olarak oluşan XML dosyasının yolunu Swagger’a bildirerek açıklamaların UI’da gözükmesini sağlamak. Bu iş için Startup.cs dosyasının içeriğini aşağıdaki gibi değiştirelim.
using System;
using System.IO;
using System.Reflection;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;
namespace AspNetCore.Swagger.Sample
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Sample Web API", Version = "v1" });
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sample Web API v1");
});
app.UseMvc();
}
}
}
- ve 32. satırlar arasında eklediğimiz kod sayesinde Swagger’ın JSON dosyası oluşurken XML dosyasının içeriğinin de yüklenmesini sağladık.
Bu işlemleri yaptıktan sonra projemizi çalıştıralım. Herhangi bir sorun yoksa aşağıdakine benzer bir ekranla karşılaşacağız.
Swagger UI’a erişirken http://localhost:5000/swagger/ adresi üzerinden ulaşıyoruz. Bu adresteki swagger ifadesini help olarak değiştirmek istediğimizde SwaggerUIOptions.RoutePrefix özelliğinin değerini değiştirmemiz yeterlidir. Biz http://localhost:5000/help/ adresi üzerinden ulaşmak istediğimizi varsayalım. Bunun için Startup.cs dosyasını aşağıdaki şekilde düzenleyelim.
using System;
using System.IO;
using System.Reflection;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;
namespace AspNetCore.Swagger.Sample
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Sample Web API", Version = "v1" });
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sample Web API v1");
c.RoutePrefix = "help";
});
app.UseMvc();
}
}
}
- satırdaki değişikliği yapıp uygulamamızı çalıştırdığımız zaman Swagger UI’a artık http://localhost:5000/help/ adresinden erişebiliriz.
Örnek projeye https://github.com/mennan/aspnetcore-swagger-sample adresinden ulaşabilirsiniz.