API geliştirme sürecinin en önemli yönlerinden biri, sağlam bir dökümantasyona sahip olmaktır. Dökümanlar, hem frontend hem de backend geliştiricileri için hayati bir kaynaktır ve API’nizin nasıl kullanılacağını anlamalarını sağlar. NSwag, ASP.NET Core projelerinde bu süreci otomatikleştirmek için mükemmel bir araçtır. Bu blog yazısında, NSwag ile nasıl başlayacağınızı ve API’nizi nasıl otomatik olarak belgelendireceğinizi adım adım anlatacağım.
NSwag Kurulumu
|
1 |
Install-Package NSwag.AspNetCore |
Startup.cs dosyasında bazı yapılandırmalar yapmanız gerekecek.|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); // Swagger dökümanını oluşturur services.AddSwaggerDocument(); services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "Swagger", Version = "v1" }); }); } // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger v1")); } app.UseHttpsRedirection(); app.UseRouting(); // Swagger dökümanını ve Swagger UI'yi ekler app.UseOpenApi(); app.UseSwaggerUi3(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); } |
/swagger yolunda erişilebilir bir Swagger UI sunacaktır.|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
/// <summary> /// Tüm hava durumu tahminlerini getirir. /// </summary> /// <returns>Tüm hava durumu tahminleri</returns> [HttpGet] public IEnumerable<WeatherForecast> Get() { Random random = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = random.Next(-20, 55), Summary = Summaries[random.Next(Summaries.Length)] }) .ToArray(); } |
Swagger UI ile Dökümantasyona Göz Atma
Yapılandırmanız tamamlandıktan sonra, projenizi çalıştırın ve tarayıcınızdan <your-root-url>/swagger adresine gidin. Burada, tüm API end-point’lerinizi görebilir ve gerçek zamanlı olarak test edebilirsiniz.
