Ikona wiadomości
Przejdź do treści stopki
  1. IronPDF
  2. Blog IronPDF
  3. Pomoc .NET
  4. OpenAPI .NET
POMOC .NET

OpenAPI .NET (jak to działa dla programistów)

Jacob Mellor, Dyrektor Technologiczny @ Team Iron
Jacob Mellor
Zaktualizowano:

OpenAPI, znane wcześniej jako Swagger, to specyfikacja służąca do tworzenia i opisywania interfejsów API typu RESTful. Pozwala programistom definiować strukturę swoich interfejsów API w standardowym formacie, umożliwiając różnym narzędziom i usługom skuteczne rozumienie interfejsu API REST oraz interakcję z nim, a także przekazywanie informacji zwrotnych. W ekosystemie .NET integracja OpenAPI .NET jest ułatwiona dzięki kilku bibliotekom i narzędziom, które ułatwiają tworzenie, dokumentówanie i wykorzystywanie interfejsów API.

W tym artykule dowiemy się o specyfikacjach obsługi OpenAPI oraz o tym, jak utworzyć plik PDF za pomocą IronPDF i zwrócić go jako odpowiedź na wywołanie API.

Konfiguracja OpenAPI w .NET

Aby rozpocząć pracę z projektem OpenAPI .NET, zazwyczaj używa się biblioteki Swashbuckle, która generuje specyfikację OpenAPI lub dokumentację dla interfejsów API ASP.NET Core.

Krok 1: Zainstaluj Swashbuckle

Najpierw należy zainstalować pakiet Swashbuckle.AspNetCore za pośrednictwem NuGet w programie Visual Studio. Można to zrobić za pomocą konsoli NuGet Package Manager Console:

Install-Package Swashbuckle.AspNetCore

Lub za pomocą interfejsu CLI platformy .NET:

dotnet add package Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore
SHELL

Krok 2: Skonfiguruj Swashbuckle

Następnie należy skonfigurować Swashbuckle w projekcie ASP.NET Core. Wymaga to aktualizacji pliku Program.cs w celu dodania usług Swagger i skonfigurowania oprogramowania pośredniczącego Swagger.

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()
$vbLabelText   $csharpLabel

Generowanie i przeglądanie dokumentacji API

Po skonfigurowaniu Swashbuckle uruchomienie aplikacji spowoduje automatyczne wygenerowanie dokumentacji OpenAPI. Opisy OpenAPI można wyświetlić, przechodząc do interfejsu Swagger UI.

Korzystanie z definicji OpenAPI

Definicje OpenAPI to potężne narzędzia, które można wykorzystać do generowania zestawów SDK dla klientów, testowania interfejsów API oraz zapewnienia spójności między różnymi usługami. Specyfikacja OpenAPI definiuje standardowy, niezależny od języka interfejs do API, który pozwala zarówno ludziom, jak i komputerom zrozumieć możliwości usługi bez dostępu do kodu źródłowego.

Rozszerzanie OpenAPI o niestandardowe adnotacje

Swashbuckle pozwala wzbogacić dokumentację OpenAPI o niestandardowe adnotacje. Te adnotacje można dodawać bezpośrednio do kontrolerów i modeli, aby zapewnić dodatkowe informacje na temat zachowania API i struktur danych.

Przykład: Adnotacje niestandardowe

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
$vbLabelText   $csharpLabel

W tym przykładzie atrybuty SwaggerOperation i SwaggerResponse służą do podania szczegółowych opisów OpenAPI i kodów odpowiedzi dla punktu końcowego.

Wynik

OpenAPI .NET (Jak to działa dla programistów): Rysunek 1 – Wynik niestandardowych adnotacji

Kliknij przycisk Wykonaj, a otrzymasz następującą odpowiedź.

OpenAPI .NET (Jak to działa dla programistów): Rysunek 2 – Wynik odpowiedzi

IronPDF

IronPDF dla ASP.NET to potężne narzędzie, które umożliwia płynne generowanie i edycję dokumentów PDF w aplikacjach ASP.NET. Dzięki intuicyjnemu API i solidnej funkcjonalności programiści mogą bez wysiłku zintegrować generowanie plików PDF ze swoimi projektami internetowymi, oferując użytkownikom ulepszone możliwości zarządzania dokumentami. Niezależnie od tego, czy chodzi o tworzenie plików PDF od podstaw, konwersję treści HTML do formatu PDF, czy dodawanie elementów dynamicznych, takich jak obrazy i tekst, IronPDF upraszcza ten proces, zapewniając wydajne i profesjonalne generowanie dokumentów.

Kroki instalacji przy użyciu menedżera pakietów NuGet:

  1. Otwórz projekt ASP.NET w programie Visual Studio i przejdź do menu "Narzędzia".
  2. Wybierz "NuGet Package Manager", a następnie kliknij "Manage NuGet Packages for Solution".
  3. W zakładce "Przeglądaj" wyszukaj "IronPDF" i wybierz żądaną wersję. Kliknij "Zainstaluj", aby dodać pakiet do swojego projektu. IronPDF i jego zależności zostaną automatycznie pobrane i zintegrowane, co pozwoli na płynne wykorzystanie jego funkcjonalności w aplikacji ASP.NET.

OpenAPI .NET (Jak to działa dla programistów): Rysunek 3 – IronPDF

Pobierz plik PDF w odpowiedzi na wywołanie API

Dodaj poniższy kod do pliku kontrolera. Wykorzystuje on bibliotekę IronPDF do utworzenia pliku PDF i zwrócenia go jako odpowiedzi na wywołanie API.

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
$vbLabelText   $csharpLabel

OpenAPI .NET (Jak to działa dla programistów): Rysunek 4 – Wynik API

Pobierz i otwórz załączony plik PDF.

OpenAPI .NET (Jak to działa dla programistów): Rysunek 5 – Wynik w formacie PDF

Wnioski

OpenAPI, znane wcześniej jako Swagger, usprawnia projektowanie i dokumentację RESTful API w ekosystemie .NET poprzez biblioteki takie jak Swashbuckle, ułatwiając automatyczne generowanie dokumentacji API dla projektów ASP.NET Core. Demonstrując synergię między OpenAPI a IronPDF, pokazaliśmy, jak wykorzystać możliwości IronPDF do generowania plików PDF z treści HTML i zwracania ich jako odpowiedzi API, wzbogacając funkcjonalność aplikacji ASP.NET. Wdrażając standardy OpenAPI i wykorzystując rozbudowane funkcje IronPDF, programiści mogą usprawnić proces tworzenia dokumentacji API i dostarczać użytkownikom dopracowane, bogate w funkcje aplikacje.

Szczegółowe informacje na temat licencji IronPDF można znaleźć w opisie licencji IronPDF. Dodatkowo możesz zapoznać się z naszym samouczkiem dotyczącym konwersji HTML do PDF, aby uzyskać dalsze wskazówki.

Często Zadawane Pytania

Jak mogę przekonwertować zawartość HTML na plik PDF w aplikacji ASP.NET?

Możesz używać IronPDF w aplikacji ASP.NET do konwersji treści HTML do formatu PDF. Wykorzystując możliwości IronPDF, możesz renderować ciągi znaków lub pliki HTML do dokumentów PDF, które następnie mogą być dostarczane jako odpowiedzi API lub zapisywane do celów zarządzania dokumentami.

Jaka jest rola OpenAPI w ekosystemie .NET?

OpenAPI odgrywa kluczową rolę w ekosystemie .NET, zapewniając znormalizowany sposób definiowania i dokumentówania interfejsów API typu RESTful. Integrację tę często ułatwiają narzędzia takie jak Swashbuckle, które pomagają generować specyfikacje OpenAPI i umożliwiają łatwe korzystanie z interfejsów API w projektach ASP.NET Core.

Jak skonfigurować Swagger UI w projekcie .NET przy użyciu Swashbuckle?

Aby skonfigurować Swagger UI w projekcie .NET przy użyciu Swashbuckle, zainstaluj pakiet Swashbuckle.AspNetCore za pośrednictwem NuGet. Następnie skonfiguruj usługi Swagger w pliku Program.cs i skonfiguruj oprogramowanie pośredniczące Swagger, aby umożliwić automatyczne generowanie i dostęp do dokumentacji API za pośrednictwem Swagger UI.

Jak mogę wygenerować zestawy SDK dla klientów na podstawie definicji OpenAPI w .NET?

Definicje OpenAPI mogą być wykorzystywane do generowania zestawów SDK dla klientów, które ułatwiają korzystanie z interfejsów API poprzez abstrakcję złożoności wywołań API. W środowisku .NET narzędzia takie jak Swashbuckle mogą generować te definicje, które następnie mogą być wykorzystywane wraz z narzędziami takimi jak AutoRest do tworzenia zestawów SDK dla klientów w różnych językach programowania.

Jakie są zalety stosowania niestandardowych adnotacji w dokumentacji OpenAPI?

Niestandardowe adnotacje w dokumentacji OpenAPI zwiększają przejrzystość i szczegółowość specyfikacji API. W .NET biblioteka Swashbuckle pozwala na użycie atrybutów takich jak SwaggerOperation i SwaggerResponse w celu dodania opisów i kodów odpowiedzi, dzięki czemu dokumentacja API jest bardziej wyczerpująca i łatwiejsza do zrozumienia dla programistów.

Jak mogę dostarczyć plik PDF jako odpowiedź API w ASP.NET Core?

W ASP.NET Core można dostarczyć plik PDF jako odpowiedź API za pomocą IronPDF. Wygeneruj plik PDF z treści HTML przy użyciu metod renderowania IronPDF, a następnie zwróć plik PDF w akcji kontrolera API, używając IActionResult w ASP.NET Core, aby wygenerować plik jako część odpowiedzi.

Jakie korzyści dla aplikacji ASP.NET płyną z połączenia OpenAPI i narzędzi do generowania plików PDF?

Połączenie OpenAPI i narzędzi do generowania plików PDF, takich jak IronPDF, w aplikacjach ASP.NET zapewnia kompleksową dokumentację API i zwiększa funkcjonalność, umożliwiając API zwracanie profesjonalnych dokumentów PDF. Integracja ta wspiera efektywne zarządzanie dokumentami i wzbogaca ogólne możliwości aplikacji.

Jacob Mellor, Dyrektor Technologiczny @ Team Iron
Jacob Mellor
  Czat z zespołem inżynierów teraz
Dyrektor ds. technologii

Jacob Mellor jest Chief Technology Officer w Iron Software i wizjonerskim inżynierem, pionierem technologii C# PDF. Jako pierwotny deweloper głównej bazy kodowej Iron Software, kształtuje architekturę produktów firmy od jej początku, przekształcając ją wspólnie z CEO Cameron Rimington w firmę liczą...

Czytaj więcej

Powiązane artykuły

30-dniowy okres próbny → Pełna wersja produktu. Bez ograniczeń. Bez karty. Bezpłatna próba

Zespol wsparcia Iron

Jestesmy online 24 godziny, 5 dni w tygodniu.
Czat
Email
Zadzwon do mnie