OpenAPI .NET (Wie es für Entwickler funktioniert)

OpenAPI, früher bekannt als Swagger, ist eine Spezifikation für die Erstellung und Beschreibung von RESTful-APIs. Sie ermöglicht es Entwicklern, die Struktur ihrer APIs in einem standardisierten Format zu definieren, so dass verschiedene Tools und Dienste die REST-API verstehen und effektiv mit ihr interagieren und Feedback geben können. Im .NET-Ökosystem wird die OpenAPI .NET-Integration durch mehrere Bibliotheken und Tools erleichtert, die das Erstellen, Dokumentieren und Verwenden von APIs vereinfachen.

In diesem Artikel lernen wir die OpenAPI-Spezifikationen kennen und erfahren, wie man mit IronPDF eine PDF-Datei erstellt und als Antwort auf einen API-Aufruf zurückgibt.

Einrichten von OpenAPI in .NET

Um mit dem OpenAPI .NET-Projekt zu beginnen, verwenden Sie normalerweise die Swashbuckle-Bibliothek, die OpenAPI-Spezifikationen oder Dokumentationen für Ihre ASP.NET Core-APIs generiert.

Schritt 1: Swashbuckle installieren

Zunächst müssen Sie das Paket "Swashbuckle.AspNetCore" über NuGet in Visual Studio installieren. Sie können dies über die NuGet Package Manager Console tun:

Install-Package Swashbuckle.AspNetCore

Oder Sie verwenden die .NET CLI:

dotnet add package Swashbuckle.AspNetCore

Schritt 2: Konfigurieren Sie Swashbuckle

Als nächstes müssen Sie Swashbuckle in Ihrem ASP.NET Core-Projekt konfigurieren. Dazu muss die Datei "Startup.cs" aktualisiert werden, um Swagger-Dienste hinzuzufügen und die Swagger-Middleware zu konfigurieren.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI description at https://aka.ms/aspnetcore/swashbuckle
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();
// Learn more about configuring Swagger/OpenAPI description at https://aka.ms/aspnetcore/swashbuckle
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()
' Learn more about configuring Swagger/OpenAPI description at https://aka.ms/aspnetcore/swashbuckle
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()

Generieren und Anzeigen von API-Dokumentation

Sobald Swashbuckle konfiguriert ist, wird bei der Ausführung Ihrer Anwendung automatisch eine OpenAPI-Dokumentation erstellt. Sie können diese OpenAPI-Beschreibungen anzeigen, indem Sie zur Swagger-Benutzeroberfläche navigieren, die normalerweise unter http://localhost:5000/swagger zugänglich ist.

Verwendung von OpenAPI-Definitionen

OpenAPI-Definitionen sind leistungsstarke Tools, die für die Erstellung von Client-SDKs, das Testen von APIs und die Gewährleistung der Konsistenz zwischen verschiedenen Diensten verwendet werden können. Die OpenAPI-Spezifikation definiert eine standardisierte, sprachunabhängige Schnittstelle zu APIs, die es sowohl Menschen als auch Computern ermöglicht, die Fähigkeiten eines Dienstes ohne Zugang zum Quellcode zu verstehen.

Erweitern von OpenAPI mit benutzerdefinierten Annotationen

Mit Swashbuckle können Sie Ihre OpenAPI-Dokumentation mit benutzerdefinierten Kommentaren erweitern. Diese Anmerkungen können direkt zu Ihren Controllern und Modellen hinzugefügt werden, um zusätzliche Informationen über das Verhalten und die Datenstrukturen der API bereitzustellen.

Beispiel: Benutzerdefinierte Annotationen

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 Namespace

In diesem Beispiel werden die Attribute "SwaggerOperation" und "SwaggerResponse" verwendet, um detaillierte OpenAPI-Beschreibungen und Antwortcodes für den Endpunkt bereitzustellen.

Ausgabe

Klicken Sie auf die Schaltfläche Ausführen und Sie erhalten die folgende Antwort.

IronPDF

IronPDF for .NET ist ein leistungsstarkes Tool, das die nahtlose Erzeugung und Bearbeitung von PDF-Dokumenten in ASP.NET-Anwendungen ermöglicht. Dank der intuitiven API und der robusten Funktionalität können Entwickler die PDF-Generierung mühelos in ihre Webprojekte integrieren und den Nutzern erweiterte Funktionen für die Dokumentenverwaltung bieten. Ob Sie PDFs von Grund auf neu erstellen, HTML-Inhalte in PDF konvertieren oder dynamische Elemente wie Bilder und Text hinzufügen, IronPDF vereinfacht den Prozess und gewährleistet eine effiziente und professionelle Dokumentenerstellung.

Schritte zur Installation mit NuGet Package Manager:

1. Öffnen Sie Ihr ASP.NET-Projekt in Visual Studio und navigieren Sie zum Menü "Tools".

2. Wählen Sie "NuGet-Paketmanager" und klicken Sie dann auf "NuGet-Pakete für Lösung verwalten"

3. Suchen Sie auf der Registerkarte "Durchsuchen" nach "IronPDF" und wählen Sie die gewünschte Version aus. Klicken Sie auf "Installieren", um das Paket zu Ihrem Projekt hinzuzufügen. IronPDF und seine Abhängigkeiten werden automatisch heruntergeladen und integriert, so dass Sie die Funktionalität in Ihrer ASP.NET-Anwendung nahtlos nutzen können.

   

PDF-Datei als Antwort auf API-Aufruf abrufen

Fügen Sie den folgenden Code in Ihre Controller-Datei ein. Er verwendet IronPDF, um eine PDF-Datei zu erstellen und eine PDF-Datei an den API-Aufruf zurückzugeben.

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)]
            });

            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 HTML to PDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Return PDF file
            var pdfBytes = pdfDocument.BinaryData;
            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)]
            });

            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 HTML to PDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Return PDF file
            var pdfBytes = pdfDocument.BinaryData;
            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))
			})

			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 HTML to PDF
			Dim renderer = New ChromePdfRenderer()
			Dim pdfDocument = renderer.RenderHtmlAsPdf(htmlContent)

			' Return PDF file
			Dim pdfBytes = pdfDocument.BinaryData
			Return File(pdfBytes, "application/pdf", "WeatherForecast.pdf")
		End Function
	End Class
End Namespace

Laden Sie die beigefügte PDF-Datei herunter und öffnen Sie sie.

Schlussfolgerung

OpenAPI, früher bekannt als Swagger, rationalisiert das Design und die Dokumentation von RESTful-APIs im .NET-Ökosystem durch Bibliotheken wie Swashbuckle und erleichtert die automatische Generierung von API-Dokumentation für ASP.NET Core-Projekte. Um die Synergie zwischen OpenAPI und IronPDF zu demonstrieren, haben wir gezeigt, wie IronPDFs Fähigkeiten genutzt werden können, um PDF-Dateien aus HTML-Inhalten zu generieren und als API-Antworten zurückzugeben und so die Funktionalität von ASP.NET-Anwendungen zu erweitern. Durch die Einbeziehung von OpenAPI-Standards und die Nutzung der robusten Funktionen von IronPDF können Entwickler ihre API-Dokumentation verbessern und den Benutzern ausgefeilte, funktionsreiche Anwendungen zur Verfügung stellen.

Ausführliche Informationen zur IronPDF-Lizenzierung finden Sie auf der IronPDF-Lizenzseite. Weitere Informationen finden Sie in unserem ausführlichen Tutorial zur Konvertierung von HTML in PDF.