OpenAPI .NET (Geliştiriciler için Nasıl Çalışır)
OpenAPI, eski adıyla Swagger, RESTful API'ler oluşturmak ve tanımlamak için bir spesifikasyondur. Geliştiricilerin API'lerinin yapısını standart bir formatta tanımlamasına olanak tanır, böylece çeşitli araçlar ve hizmetler REST API'yi etkili bir şekilde anlayabilir, etkileşimde bulunabilir ve geri bildirim sağlayabilir. .NET ekosisteminde OpenAPI .NET entegrasyonu, API'leri oluşturmayı, belgelemeyi ve kullanmayı kolaylaştıran birçok kütüphane ve araçla sağlanır.
Bu makalede, OpenAPI destek spesifikasyonlarını nasıl oluşturacağımızı ve IronPDF kullanarak bir PDF dosyası oluşturup bunu bir API çağrısı yanıtı olarak nasıl döndüreceğimizi öğreneceğiz.
.NET'te OpenAPI Kurulumu
OpenAPI .NET projesine başlamak için genellikle, ASP.NET Core API'leriniz için OpenAPI spesifikasyonu veya dokümantasyonu oluşturan Swashbuckle kütüphanesini kullanırsınız.
Adım 1: Swashbuckle Yükleme
Öncelikle, Visual Studio'da Swashbuckle.AspNetCore paketini NuGet aracılığıyla yüklemeniz gerekir. Bu işlemi NuGet Paket Yöneticisi Konsolu'nu kullanarak yapabilirsiniz:
Install-Package Swashbuckle.AspNetCore
Veya .NET CLI kullanarak:
dotnet add package Swashbuckle.AspNetCoredotnet add package Swashbuckle.AspNetCoreAdım 2: Swashbuckle'ı Yapılandırma
Sonra, ASP.NET Core projenizde Swashbuckle'ı yapılandırmanız gerekiyor. Bu, Swagger hizmetlerini eklemek ve Swagger ara yazılımını yapılandırmak için Program.cs dosyasını güncellemeyi içerir.
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddControllers();
// Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddControllers();
// Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();Dim builder = WebApplication.CreateBuilder(args)
' Add services to the container.
builder.Services.AddControllers()
' Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer()
builder.Services.AddSwaggerGen()
Dim app = builder.Build()
' Configure the HTTP request pipeline.
If app.Environment.IsDevelopment() Then
app.UseSwagger()
app.UseSwaggerUI()
End If
app.UseHttpsRedirection()
app.UseAuthorization()
app.MapControllers()
app.Run()API Dokümantasyonu Üretme ve Görüntüleme
Swashbuckle yapılandırıldığında, uygulamanızı çalıştırdığınızda otomatik olarak OpenAPI dokümantasyonu üretilir. Bu OpenAPI açıklamalarını görmek için Swagger UI arayüzü'ne giderek görebilirsiniz.
OpenAPI Tanımlarını Kullanma
OpenAPI tanımları, istemci SDK'ları oluşturma, API'ları test etme ve farklı servisler arasında tutarlılığı sağlama gibi amaçlar için güçlü araçlardır. OpenAPI spesifikasyonu, API'ların standardize edilmiş, dilden bağımsız bir arayüzünü tanımlar; bu, hem insanlar hem de bilgisayarlar için kaynağına erişim olmadan bir hizmetin yeteneklerini anlamalarına olanak tanır.
Özel Anotasyonlarla OpenAPI'yi Genişletme
Swashbuckle, OpenAPI dokümantasyonunuzu özel anotasyonlarla zenginleştirmenize imkan tanır. Bu anotasyonlar, API'nin davranışı ve veri yapıları hakkında ek bilgi sağlamak için doğrudan denetleyicilerinize ve modellerinize eklenebilir.
Örnek: Özel Anotasyonlar
using Microsoft.AspNetCore.Mvc;
namespace WebApplication8.Controllers
{
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger<WeatherForecastController> _logger;
public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
[SwaggerOperation(Summary = "Gets the weather forecast for the next 5 days")]
[SwaggerResponse(200, "Successfully retrieved weather forecast")]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
}
}using Microsoft.AspNetCore.Mvc;
namespace WebApplication8.Controllers
{
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger<WeatherForecastController> _logger;
public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
[SwaggerOperation(Summary = "Gets the weather forecast for the next 5 days")]
[SwaggerResponse(200, "Successfully retrieved weather forecast")]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
}
}Imports Microsoft.AspNetCore.Mvc
Namespace WebApplication8.Controllers
<ApiController>
<Route("[controller]")>
Public Class WeatherForecastController
Inherits ControllerBase
Private Shared ReadOnly Summaries() As String = { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }
Private ReadOnly _logger As ILogger(Of WeatherForecastController)
Public Sub New(ByVal logger As ILogger(Of WeatherForecastController))
_logger = logger
End Sub
<HttpGet(Name := "GetWeatherForecast")>
<SwaggerOperation(Summary := "Gets the weather forecast for the next 5 days")>
<SwaggerResponse(200, "Successfully retrieved weather forecast")>
Public Function [Get]() As IEnumerable(Of WeatherForecast)
Return Enumerable.Range(1, 5).Select(Function(index) New WeatherForecast With {
.Date = DateTime.Now.AddDays(index),
.TemperatureC = Random.Shared.Next(-20, 55),
.Summary = Summaries(Random.Shared.Next(Summaries.Length))
}).ToArray()
End Function
End Class
End NamespaceBu örnekte, SwaggerOperation ve SwaggerResponse özellikleri, uç nokta için ayrıntılı OpenAPI açıklamaları ve yanıt kodları sağlamak amacıyla kullanılıyor.
Çıktı
Execute butonuna tıklayın ve aşağıdaki yanıtı alacaksınız.
IronPDF
IronPDF for ASP.NET, ASP.NET uygulamalarında kesintisiz PDF belge oluşturma ve düzenlemeyi sağlayan güçlü bir araçtır. Sezgisel API'si ve sağlam işlevselliği ile geliştiriciler, web projelerine PDF oluşturmayı zahmetsizce entegre edebilir, kullanıcılara gelişmiş belge yönetimi yetenekleri sunabilir. Sıfırdan PDF oluşturma, HTML içeriğini PDF'ye dönüştürme veya resim ve metin gibi dinamik öğeler ekleme olsun, IronPDF süreci basitleştirir, verimli ve profesyonel belge oluşturmayı sağlar.
NuGet Paket Yöneticisi kullanarak yükleme adımları:
- ASP.NET projenizi Visual Studio'da açın ve "Araçlar" menüsüne gidin.
- "NuGet Paket Yöneticisi"ni seçin ve ardından "Solution için NuGet Paketlerini Yönet" seçeneğine tıklayın.
- "Gözat" sekmesinde "IronPDF" arayın ve istenen sürümü seçin. Projeye paketi eklemek için "Yükle" seçeneğine tıklayın. IronPDF ve bağımlılıkları otomatik olarak indirilecek ve entegre edilecek, böylece ASP.NET uygulamanızda işlevselliğinden sorunsuz bir şekilde yararlanmaya başlayabilirsiniz.
API Çağrısına Yanıt Olarak PDF Dosyası Alın
Aşağıdaki kodu denetleyici dosyanıza ekleyin, IronPDF kullanarak bir PDF dosyası oluşturur ve bunu API çağrısına yanıt olarak döndürür.
using Microsoft.AspNetCore.Mvc;
using IronPdf;
namespace WebApplication8.Controllers
{
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger<WeatherForecastController> _logger;
public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
public IActionResult GetWeatherForecastPdf()
{
var htmlContent = @"
<html>
<head>
<title>Weather Forecast</title>
</head>
<body>
<h1>Weather Forecast</h1>
<table>
<tr>
<th>Date</th>
<th>Temperature (Celsius)</th>
<th>Summary</th>
</tr>";
var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
});
// Iterate over the forecasts and add data to the HTML string
foreach (var forecast in forecasts)
{
htmlContent += $@"
<tr>
<td>{forecast.Date.ToShortDateString()}</td>
<td>{forecast.TemperatureC}</td>
<td>{forecast.Summary}</td>
</tr>";
}
htmlContent += @"
</table>
</body>
</html>";
// Convert the HTML string to a PDF using IronPDF
var renderer = new ChromePdfRenderer();
var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);
// Retrieve the byte array of the generated PDF
var pdfBytes = pdfDocument.BinaryData;
// Return the PDF file to the client
return File(pdfBytes, "application/pdf", "WeatherForecast.pdf");
}
}
}using Microsoft.AspNetCore.Mvc;
using IronPdf;
namespace WebApplication8.Controllers
{
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger<WeatherForecastController> _logger;
public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
public IActionResult GetWeatherForecastPdf()
{
var htmlContent = @"
<html>
<head>
<title>Weather Forecast</title>
</head>
<body>
<h1>Weather Forecast</h1>
<table>
<tr>
<th>Date</th>
<th>Temperature (Celsius)</th>
<th>Summary</th>
</tr>";
var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
});
// Iterate over the forecasts and add data to the HTML string
foreach (var forecast in forecasts)
{
htmlContent += $@"
<tr>
<td>{forecast.Date.ToShortDateString()}</td>
<td>{forecast.TemperatureC}</td>
<td>{forecast.Summary}</td>
</tr>";
}
htmlContent += @"
</table>
</body>
</html>";
// Convert the HTML string to a PDF using IronPDF
var renderer = new ChromePdfRenderer();
var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);
// Retrieve the byte array of the generated PDF
var pdfBytes = pdfDocument.BinaryData;
// Return the PDF file to the client
return File(pdfBytes, "application/pdf", "WeatherForecast.pdf");
}
}
}Imports Microsoft.AspNetCore.Mvc
Imports IronPdf
Namespace WebApplication8.Controllers
<ApiController>
<Route("[controller]")>
Public Class WeatherForecastController
Inherits ControllerBase
Private Shared ReadOnly Summaries() As String = { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }
Private ReadOnly _logger As ILogger(Of WeatherForecastController)
Public Sub New(ByVal logger As ILogger(Of WeatherForecastController))
_logger = logger
End Sub
<HttpGet(Name := "GetWeatherForecast")>
Public Function GetWeatherForecastPdf() As IActionResult
Dim htmlContent = "
<html>
<head>
<title>Weather Forecast</title>
</head>
<body>
<h1>Weather Forecast</h1>
<table>
<tr>
<th>Date</th>
<th>Temperature (Celsius)</th>
<th>Summary</th>
</tr>"
Dim forecasts = Enumerable.Range(1, 5).Select(Function(index) New WeatherForecast With {
.Date = DateTime.Now.AddDays(index),
.TemperatureC = Random.Shared.Next(-20, 55),
.Summary = Summaries(Random.Shared.Next(Summaries.Length))
})
' Iterate over the forecasts and add data to the HTML string
For Each forecast In forecasts
htmlContent &= $"
<tr>
<td>{forecast.Date.ToShortDateString()}</td>
<td>{forecast.TemperatureC}</td>
<td>{forecast.Summary}</td>
</tr>"
Next forecast
htmlContent &= "
</table>
</body>
</html>"
' Convert the HTML string to a PDF using IronPDF
Dim renderer = New ChromePdfRenderer()
Dim pdfDocument = renderer.RenderHtmlAsPdf(htmlContent)
' Retrieve the byte array of the generated PDF
Dim pdfBytes = pdfDocument.BinaryData
' Return the PDF file to the client
Return File(pdfBytes, "application/pdf", "WeatherForecast.pdf")
End Function
End Class
End Namespace
Ekteki PDF dosyasını indirin ve açın.
Sonuç
Eski adıyla Swagger olan OpenAPI, RESTful API tasarımını ve dokümantasyonunu .NET ekosisteminde Swashbuckle gibi kütüphanelerle kolaylaştırır ve ASP.NET Core projeleri için otomatik API dokümantasyonu üretimini destekler. OpenAPI ve IronPDF arasındaki sinerjiyi göstererek, IronPDF'in yeteneklerini HTML içeriğinden PDF dosyaları oluşturmak ve bunları API yanıtı olarak döndürmek için nasıl kullanabileceğimizi ve böylece ASP.NET uygulamalarının işlevselliğini zenginleştirdiğimizi sergiledik. OpenAPI standartlarını benimseyerek ve IronPDF'in sağlam özelliklerinden yararlanarak, geliştiriciler API dokümantasyon uygulamalarını geliştirebilir ve son kullanıcılara cilalı, özellik açısından zengin uygulamalar sunabilir.
IronPDF lisanslama hakkında ayrıntılı bilgi için lütfen IronPDF lisanslama detayları sayfasına bakın. Ayrıca, daha fazla rehberlik için HTML'den PDF'e dönüşüm eğiticimizi keşfedebilirsiniz.
Sıkça Sorulan Sorular
Bir ASP.NET uygulamasında HTML içeriğini PDF'ye nasıl dönüştürebilirim?
Bir ASP.NET uygulamasında HTML içeriğini PDF'ye dönüştürmek için IronPDF kullanabilirsiniz. IronPDF'nin yeteneklerini kullanarak, HTML dizesi veya dosyalarını PDF belgelerine dönüştürebilir ve ardından API yanıtları olarak sunabilir veya belge yönetimi için kaydedebilirsiniz.
.NET ekosisteminde OpenAPI'nin rolü nedir?
OpenAPI, RESTful API'leri tanımlamak ve belgelemek için standart bir yol sağlayarak .NET ekosisteminde önemli bir rol oynar. Bu entegrasyon genellikle OpenAPI spesifikasyonlarını üretmeye yardımcı olan Swashbuckle gibi araçlar üzerinden sağlanarak, ASP.NET Core projelerinde API tüketimini kolaylaştırır.
Swashbuckle kullanarak bir .NET projesinde Swagger UI'yi nasıl kurarım?
Swashbuckle kullanarak bir .NET projesinde Swagger UI kurmak için, NuGet üzerinden Swashbuckle.AspNetCore paketini yükleyin. Daha sonra, Program.cs dosyanızda Swagger servislerini yapılandırın ve Swagger ara yazılımını kurarak API dokümantasyonunun Swagger UI aracılığıyla otomatik oluşturulmasını ve erişilmesini sağlayın.
.NET'te OpenAPI tanımlarından istemci SDK'ları nasıl oluşturabilirim?
OpenAPI tanımları, API çağrılarının karmaşıklığını soyutlayarak API tüketimini kolaylaştıran istemci SDK'ları oluşturmak için kullanılabilir. .NET'te, Swashbuckle gibi araçlar bu tanımları oluşturabilir, ardından AutoRest gibi araçlarla bu tanımları çeşitli programlama dillerinde istemci SDK'larına dönüştürebilirsiniz.
OpenAPI belgelerinde özel açıklamalar kullanmanın avantajları nelerdir?
OpenAPI belgelerindeki özel açıklamalar, API spesifikasyonlarının daha net ve detaylı olmasını sağlar. .NET'te Swashbuckle, açıklamalar ve yanıt kodları eklemek için SwaggerOperation ve SwaggerResponse gibi öznitelikler kullanma imkanı sağlar, bu da API belgelerini geliştiriciler için daha bilgilendirici ve anlaşılır hale getirir.
PDF dosyasını ASP.NET Core ile nasıl bir API yanıtı olarak teslim edebilirim?
IronPDF kullanarak bir PDF dosyasını ASP.NET Core ile bir API yanıtı olarak teslim edebilirsiniz. IronPDF'nin render yöntemlerini kullanarak HTML içeriğinden PDF oluşturun ve sonunda PDF dosyasını API denetleyici eyleminizde ASP.NET Core'nin IActionResult aracılığıyla yanıtın bir parçası olarak işleyin.
OpenAPI ve PDF oluşturma araçlarını ASP.NET uygulamalarında birleştirerek ne gibi yararlar elde edersiniz?
ASP.NET uygulamalarında OpenAPI ve IronPDF gibi PDF oluşturma araçlarının birleştirilmesi, kapsamlı API belgeleri ve profesyonel PDF belgeleri döndürme özelliği sağlayarak işlevselliği geliştirir. Bu entegrasyon, verimli belge yönetimini destekler ve uygulamanın genel yeteneklerini zenginleştirir.
Ücretsiz Başlayın
Ücretsiz Başlayın
Ücretsiz Canlı Demo Rezervasyonu
Kredi kartı veya hesap oluşturma gerektirmez
