Merhaba arkadaşlar, bugün sizlerle beraber .net core 3.0 web api ve swagger entegrasyonunu yapacağız. Öncelikle swaggerdan biraz bahsedelim. Swagger, apilerimize ui desteği sağlayarak doğal bir dokümantasyon oluşturmamızı sağlayan ve OpenAPI bildirimlerine uyan açık kaynak bir araçtır. Apilerde contract denen alınacak request ve verilecek response sözleşmesini standart hale getirerek hem insanların hemde makinelerin anlayabileceği bir standart sunar.
Şimdi örneğimize geçerek .net core apimize swagger dökümanı eklemeye çalışalım.
Öncelikle Web Apimizden başlayalım. Motorcycle web api bize motorsiklet ekleme,silme,güncelleme ve listeleme gibi işlemler sağlayacak. Önce interfacemizi daha sonra servisimizi yazalım.
public interface IRepository<T> where T : class
{
IEnumerable<T> Get();
T GetById(int id);
bool Add(T model);
T Update(T model,int id);
bool Delete(int id);
}
public class MotorCycleRepository : IRepository<MotorCycle>
{
public static List<MotorCycle> motorCycles = new List<MotorCycle> {
new MotorCycle{ Id=1,Model="Honda - CBR 1000 RR",IsAutomatic=false,Year=2019 },
new MotorCycle{ Id=2,Model="Honda - CBR 500 R",IsAutomatic=false,Year=2019 },
new MotorCycle{ Id=3,Model="Yamaha - Xmax - 250",IsAutomatic=true,Year=2019 },
new MotorCycle{ Id=4,Model="Yamaha - R25",IsAutomatic=false,Year=2019 }
};
public bool Add(MotorCycle motorCycle)
{
if (motorCycle == null)
return false;
motorCycles.Add(motorCycle);
return true;
}
public bool Delete(int id)
{
if (id <= 0)
return false;
var motorCycle = GetById(id);
if (motorCycle == null)
return false;
return motorCycles.Remove(motorCycle);
}
public IEnumerable<MotorCycle> Get()
{
return motorCycles;
}
public MotorCycle GetById(int id)
{
if (id <= 0)
return null;
var motorCycle = motorCycles.Find(x => x.Id == id);
return motorCycle;
}
public MotorCycle Update(MotorCycle motorCycle, int id)
{
if (motorCycle == null || id <= 0)
return null;
var oldMotorCyle = GetById(id);
if (oldMotorCyle == null)
return null;
oldMotorCyle.Id = motorCycle.Id > 0 ? motorCycle.Id : oldMotorCyle.Id;
oldMotorCyle.Model = motorCycle.Model;
oldMotorCyle.IsAutomatic = motorCycle.IsAutomatic;
oldMotorCyle.Year = motorCycle.Year;
return oldMotorCyle;
}
}
Servisimizi dependency injection için singleton olarak interface ile eşleştirerek, controllerımızı oluşturalım.
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSingleton(typeof(IRepository<MotorCycle>), typeof(MotorCycleRepository));
}
[Route("api/motorcycle")]
[ApiController]
public class MotorCycleController : ControllerBase
{
private readonly IRepository<MotorCycle> _motorCycleRepository;
public MotorCycleController(IRepository<MotorCycle> motorCycleRepository)
{
_motorCycleRepository = motorCycleRepository;
}
// GET: api/motorcycle
[HttpGet]
public IActionResult Get()
{
var list = _motorCycleRepository.Get();
if (list != null)
return Ok(list);
return NotFound(list);
}
// GET: api/motorcycle/5
[HttpGet("{id}", Name = "Get")]
public IActionResult Get(int id)
{
var model = _motorCycleRepository.GetById(id);
if (model != null)
return Ok(model);
return NotFound(model);
}
// POST: api/motorcycle
[HttpPost]
public IActionResult Post([FromBody] MotorCycle request)
{
var result= _motorCycleRepository.Add(request);
if (result)
return Ok(result);
return BadRequest(result);
}
// PUT: api/motorcycle/5
[HttpPut("{id}")]
public IActionResult Put(int id, [FromBody] MotorCycle request)
{
var model = _motorCycleRepository.Update(request, id);
if (model!=null)
return Ok(model);
return NotFound(model);
}
// DELETE: api/motorcycle/5
[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
var result = _motorCycleRepository.Delete(id);
if (result)
return Ok(result);
return NotFound(result);
}
}
Evet şuan apimizi yazdık ben bir postman collection oluşturarak ilgili sorguları buraya kaydettim. Postman üzerindeki enviroment variable kısmını kullanarak da baseurlimi belirttim.
Fakat farkettiyseniz apimiz ayağa kalktığında bizi karşılayan, bize bilgi veren herhangi bir ui bulunmuyor. Şimdi bu problemi çözmek için yazının asıl amacı swagger entegrasyouna geçelim.
Öncelikle Swashbuckle.AspNetCore nuget paketini indirelim .
Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4
(Diğer Versionlar .net core 3.0 için şuanda sorun çıkartıyor.)
Şimdi Startup sınıfnımızı swagger kullanmak için düzenleyelim.
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSingleton(typeof(IRepository<MotorCycle>), typeof(MotorCycleRepository));
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Motorcycle Api Swagger",
Description = "MotorCycle .Net Core 3.0 Api Swagger Documentation",
TermsOfService = new Uri("http://swagger.io/terms/"),
Contact = new OpenApiContact
{
Name = "Enes Aysan",
Url = new Uri("http://www.enesaysan.com"),
Email = "enesaysan8@gmail.com"
}
});
});
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Motorcycle API V1");
c.RoutePrefix = string.Empty;
});
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
Swagger dokümanımızı daha detaylı hale getirmek için xml yorumları kullanacağız. Bunu aktif etmek için projemize sağ tıklayalım ve edit seçeneğini seçerek aşağıdaki konfigürasyonu ekleyelim.
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>
Startup sınıfımızda SwaggerDoc bloğu altına XML yorumlarımızı kullanmak için
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
ilgili kod bloğunu ekleyelim. Daha sonra metotlarımızın başına “///” koyarak aşağıda ki örnekte olduğu gibi vermek istediğimiz bilgileri yazalım.
/// <summary>
/// Add motorcycle.
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /api/motorcycle
/// {
/// "Id":2000,
/// "Model":"Honda - Africa Twin -1000",
/// "IsAutomatic":true,
/// "Year":2020
/// }
///
/// </remarks>
/// <param name="request"></param>
/// <returns>A newly created motorcycle</returns>
/// <response code="200">Returns the newly created motorcycle</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(200)]
[ProducesResponseType(400)]
public IActionResult Post([FromBody] MotorCycle request)
{
var result= _motorCycleRepository.Add(request);
if (result)
return Ok(result);
return BadRequest(result);
}
Uygulamayı çalıştırarak swagger dokümantasyonunun tadını çıkaralım. 😀
Evet arkadaşlar başarılı bir şekilde .Net Core 3.0 ile yazılan web apimize swagger dökümantasyonu ekledik. Umarım faydalı olmuştur.
Proje Linki : https://github.com/EnesAys/NetCoreApiandSwagger
Kaynaklar
https://docs.microsoft.com/tr-tr/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.0&tabs=visual-studio
