OpenAPI .NET (Geliştiriciler için Nasıl Çalışır)
Önceden Swagger olarak bilinen OpenAPI, RESTful API'lerin oluşturulması ve tanımlanması 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 ile etkili bir şekilde etkileşimde bulunabilir ve geri bildirim sağlayabilir. .NET ekosisteminde, OpenAPI .NET entegrasyonu, API'leri oluşturmayı, belgelerini yazmayı ve tüketmeyi kolaylaştıran birkaç kütüphane ve araçla desteklenir.
Bu makalede, OpenAPI destek spesifikasyonlarını ve IronPDF kullanarak bir PDF dosyası oluşturup bunu bir API çağrısı yanıtı olarak nasıl geri 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 üreten Swashbuckle kütüphanesini kullanırsınız.
Adım 1: Swashbuckle Kurulumu
Öncelikle, Visual Studio'da Swashbuckle.AspNetCore paketini NuGet aracılığıyla yüklemeniz gerekiyor. Bunu NuGet Paket Yöneticisi Konsolu'nu kullanarak yapabilirsiniz:
Install-Package Swashbuckle.AspNetCore
Ya da .NET CLI kullanarak:
dotnet add package Swashbuckle.AspNetCoredotnet add package Swashbuckle.AspNetCoreAdım 2: Swashbuckle Yapılandırması
Sonra, ASP.NET Core projenizde Swashbuckle'ı yapılandırmanız gerekmektedir. Bu, Swagger hizmetlerini eklemek ve Swagger ara yazılımını yapılandırmak için Program.cs dosyasını güncellemeyi gerektirir.
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 Belgelerinin Oluşturulması ve Görüntülenmesi
Swashbuckle yapılandırıldıktan sonra, uygulamanızı çalıştırdığınızda otomatik olarak OpenAPI belgeleri oluşturulacaktır. Bu OpenAPI açıklamalarını görmek için Swagger UI arayüzüne giderek görüntüleyebilirsiniz.
OpenAPI Tanımlarının Kullanımı
OpenAPI tanımları, istemci SDK'ları oluşturmak, API'leri test etmek ve farklı hizmetler arasında tutarlılığı sağlamak için kullanılabilecek güçlü araçlardır. OpenAPI spesifikasyonu, API'lere standardize edilmiş, dil agnostik bir arayüz tanımlar ki bu, bir servisin yeteneklerini kaynak koda erişmeden anlamasına olanak tanır hem insanlar hem de bilgisayarlar için.
OpenAPI'yi Özel Anotasyonlarla Genişletme
Swashbuckle, OpenAPI belgelerinizi özel anotasyonlarla geliştirmenize olanak tanır. Bu anotasyonlar, API'nin davranışı ve veri yapıları hakkında ek bilgi sağlamak için doğrudan kontrolörlerinize 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, endpoint için ayrıntılı OpenAPI açıklamaları ve yanıt kodları sağlamak amacıyla SwaggerOperation ve SwaggerResponse özellikleri kullanılır.
Çıktı
Çalıştır düğmesine tıklayın ve aşağıdaki yanıtı alacaksınız.
IronPDF
IronPDF for ASP.NET, ASP.NET uygulamaları içinde PDF belgelerinin sorunsuz şekilde oluşturulmasını ve manipüle edilmesini sağlayan güçlü bir araçtır. Kullanıcı dostu API'si ve güçlü fonksiyonelliği sayesinde, geliştiriciler PDF oluşturmayı web projelerine zahmetsizce entegre edebilir, kullanıcılara geliştirilmiş belge yönetimi yetenekleri sunabilir. İster sıfırdan PDF oluştursun, HTML içeriğini PDF'ye dönüştürsün, isterse resimler ve metinler gibi dinamik elemanlar eklesin, IronPDF süreci basitleştirir, etkin ve profesyonel belge üretimini sağlar.
NuGet Paket Yöneticisi kullanımı için 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 "Çözüm için NuGet Paketlerini Yönet"e tıklayın.
- "Gözat" sekmesinde "IronPDF" için arama yapın ve istenen sürümü seçin. Paketinizi projenize eklemek için "Yükle"ye tıklayın. IronPDF ve bağımlılıkları otomatik olarak indirilecek ve entegre edilecek, böylece işlevselliğini ASP.NET uygulamanızda sorunsuz şekilde kullanmaya başlayabilirsiniz.
API Çağrısına Yanıt Olarak PDF Dosyasını Al
Denetleyici dosyanıza aşağıdaki kodu ekleyin, bu kod IronPDF kullanarak bir PDF dosyası oluşturur ve 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
Ekli PDF dosyasını indirin ve açın.
Sonuç
Önceden Swagger olarak bilinen OpenAPI, Swashbuckle gibi kütüphaneler aracılığıyla .NET ekosisteminde RESTful API tasarımını ve belgelenmesini kolaylaştırır, ASP.NET Core projeleri için otomatik API belgeleme nesillerini kolaylaştırır. OpenAPI ve IronPDF arasında sinerjiyi göstererek, HTML içeriğinden PDF dosyalarının nasıl üretileceği ve bunların API yanıtı olarak nasıl dönüleceği gösterilerek, ASP.NET uygulamalarının işlevselliğinin zenginleşmesi sağlanmıştır. OpenAPI standartlarını benimseyerek ve IronPDF'in güçlü özelliklerinden faydalanarak, geliştiriciler API belgeleme uygulamalarını geliştirebilir ve kullanıcılara iyi cilalı, işlev açısından zengin uygulamalar sunabilir.
IronPDF lisanslama hakkında ayrıntılı bilgi için lütfen IronPDF lisans bilgileri'ne bakın. Ayrıca, HTML'den PDF'e dönüştürme eğitimimizi keşfedebilirsiniz.
Sıkça Sorulan Sorular
ASP.NET uygulamasında HTML içeriğini nasıl PDF'ye dönüştürebilirim?
HTML içeriğini PDF'ye dönüştürmek için bir ASP.NET uygulamasında IronPDF kullanabilirsiniz. IronPDF'in yeteneklerinden yararlanarak, HTML dizgelerini veya dosyalarını PDF belgelerine dönüştürebilir, böylece bunları API yanıtı olarak sunabilir veya belge yönetimi amaçları için kaydedebilirsiniz.
.NET ekosisteminde OpenAPI'nin rolü nedir?
OpenAPI, .NET ekosisteminde RESTful API'leri tanımlamak ve belgelemek için standart bir yol sağlayarak önemli bir rol oynar. Bu entegrasyon genellikle, OpenAPI spesifikasyonları oluşturmaya ve ASP.NET Core projeleri içinde API tüketimini kolaylaştırmaya yardımcı olan Swashbuckle gibi araçlar aracılığıyla gerçekleştirilir.
Bir .NET projesinde Swashbuckle ile Swagger UI'ı nasıl kurarım?
Swashbuckle kullanarak bir .NET projesinde Swagger UI'ı kurmak için, NuGet üzerinden Swashbuckle.AspNetCore paketini yükleyin. Ardından, Program.cs dosyanızda Swagger hizmetlerini yapılandırın ve Swagger ara yazılımını kurarak Swagger UI aracılığıyla API dokümantasyonunun otomatik olarak oluşturulmasını ve erişilmesini sağlayın.
.NET'te OpenAPI tanımlarından istemci SDK'larını nasıl oluşturabilirim?
İstemci SDK'larının API çağrılarının karmaşıklığını soyutlayarak API tüketimini kolaylaştırdığı OpenAPI tanımları, istemci SDK'ları oluşturmak için kullanılabilir. .NET'te, bu tanımları oluşturmak için Swashbuckle gibi araçlar kullanılabilir ve daha sonra AutoRest gibi araçlarla çeşitli programlama dillerinde istemci SDK'ları oluşturulabilir.
OpenAPI belgelerinde özel açıklamalar kullanmanın avantajları nelerdir?
OpenAPI belgelerinde özel açıklamalar, API spesifikasyonlarının netliğini ve ayrıntılı bilgisini artırır. .NET'te, Swashbuckle'ın SwaggerOperation ve SwaggerResponse gibi açıklamaları kullanmanıza olanak tanır, bu da API belgelerini geliştiriciler için daha bilgilendirici ve anlaşılır hale getirir.
Bir PDF dosyasını ASP.NET Core'da bir API yanıtı olarak nasıl sunabilirim?
IronPDF kullanarak bir PDF dosyasını ASP.NET Core'da bir API yanıtı olarak sunabilirsiniz. HTML içeriğinden PDF oluşturarak IronPDF'in render yöntemlerini kullanın ve ASP.NET Core'un IActionResult ile yanıtın bir parçası olarak dosyayı çıkış alarak API denetleyici işleminizde PDF dosyasını geri dönün.
OpenAPI ve PDF oluşturma araçlarını ASP.NET uygulamalarında birleştirmenin avantajları nelerdir?
ASP.NET uygulamalarında OpenAPI ve IronPDF gibi PDF oluşturma araçlarının birleştirilmesi kapsamlı API belgeleri sunar ve API'lerin profesyonel PDF belgeleri geri döndürebilmesini sağlayarak işlevselliği artırır. Bu entegrasyon, etkili belge yönetimini destekler ve uygulamanın genel yeteneklerini zenginleştirir.
Ücretsiz başlamak için
Ücretsiz başlamak için
Ücretsiz Canlı Demo Rezervasyonu Yapın
Kredi kartı veya hesap oluşturma gerekli değil
