OpenAPI .NET (Comment ça marche pour les développeurs)

OpenAPI, anciennement connu sous le nom de Swagger, est une spécification pour la construction et la description d'API RESTful. Elle permet aux développeurs de définir la structure de leurs API dans un format standardisé, ce qui permet à divers outils et services de comprendre et d'interagir avec l'API REST de manière efficace et de fournir un retour d'information. Dans l'écosystème .NET, l'intégration d'OpenAPI .NET est facilitée par plusieurs bibliothèques et outils qui facilitent la création, la documentation et la consommation d'API.

Dans cet article, nous allons découvrir les spécifications de prise en charge de l'OpenAPI et apprendre à créer un fichier PDF à l'aide d'IronPDF et à le renvoyer en tant que réponse à un appel d'API.

Mise en place d'OpenAPI dans .NET

Pour démarrer avec le projet OpenAPI .NET, vous utilisez généralement la bibliothèque Swashbuckle, qui génère la spécification ou la documentation OpenAPI pour vos API ASP.NET Core.

Étape 1 : Installer Swashbuckle

Tout d'abord, vous devez installer le paquet Swashbuckle.AspNetCore via NuGet dans Visual Studio. Vous pouvez le faire à l'aide de la console NuGet Package Manager :

Install-Package Swashbuckle.AspNetCore

Ou en utilisant le CLI .NET :

dotnet add package Swashbuckle.AspNetCore

Étape 2 : Configuration de Swashbuckle

Ensuite, vous devez configurer Swashbuckle dans votre projet ASP.NET Core. Il s'agit de mettre à jour le fichier Startup.cs pour ajouter les services Swagger et configurer le middleware Swagger.

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()

Générer et consulter la documentation de l'API

Une fois Swashbuckle configuré, l'exécution de votre application génère automatiquement la documentation OpenAPI. Vous pouvez consulter ces descriptions d'OpenAPI en vous rendant sur la pageInterface Swagger UI.

Utilisation des définitions OpenAPI

Les définitions OpenAPI sont des outils puissants qui peuvent être utilisés pour générer des SDK clients, tester les API et assurer la cohérence entre différents services. La spécification OpenAPI définit une interface standard, indépendante du langage, pour les API, qui permet aux humains et aux ordinateurs de comprendre les capacités d'un service sans avoir accès au code source.

Extension de l'OpenAPI avec des annotations personnalisées

Swashbuckle vous permet d'enrichir votre documentation OpenAPI avec des annotations personnalisées. Ces annotations peuvent être ajoutées directement à vos contrôleurs et modèles pour fournir des informations supplémentaires sur le comportement et les structures de données de l'API.

Exemple : Annotations personnalisées

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

Dans cet exemple, les attributs SwaggerOperation et SwaggerResponse sont utilisés pour fournir des descriptions OpenAPI détaillées et des codes de réponse pour le point final.

Sortie

Cliquez sur le bouton Exécuter et vous obtiendrez la réponse suivante.

IronPDF

IronPDF for .NET est un outil puissant qui permet de générer et de manipuler en toute transparence des documents PDF au sein d'applications ASP.NET. Grâce à son API intuitive et à ses fonctionnalités robustes, les développeurs peuvent intégrer sans effort la génération de PDF dans leurs projets web, offrant ainsi aux utilisateurs des capacités de gestion de documents améliorées. Qu'il s'agisse de créer des PDF à partir de zéro, de convertir du contenu HTML en PDF ou d'ajouter des éléments dynamiques tels que des images et du texte, IronPDF simplifie le processus, garantissant une génération de documents efficace et professionnelle.

Étapes de l'installation à l'aide du gestionnaire de paquets NuGet :

1. Ouvrez votre projet ASP.NET dans Visual Studio et accédez au menu "Outils".

2. Sélectionnez "NuGet Package Manager" et cliquez sur "Manage NuGet Packages for Solution"

3. Dans l'onglet "Parcourir", recherchez "IronPDF" et sélectionnez la version souhaitée. Cliquez sur "Install" pour ajouter le paquet à votre projet. IronPDF et ses dépendances seront automatiquement téléchargés et intégrés, ce qui vous permettra de commencer à tirer parti de ses fonctionnalités dans votre application ASP.NET en toute transparence.

   

Obtenir un fichier PDF en réponse à un appel API

Ajoutez le code suivant à votre fichier contrôleur, il utilise IronPDF pour créer un fichier PDF et renvoyer un fichier PDF à l'appel 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)]
            });

            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

Téléchargez et ouvrez le fichier PDF ci-joint.

Conclusion

OpenAPI, anciennement connu sous le nom de Swagger, rationalise la conception et la documentation des API RESTful dans l'écosystème .NET grâce à des bibliothèques comme Swashbuckle, facilitant la génération automatique de la documentation des API pour les projets ASP.NET Core. Démontrant la synergie entre OpenAPI et IronPDF, nous avons expliqué comment utiliser les capacités d'IronPDF pour générer des fichiers PDF à partir d'un contenu HTML et les renvoyer sous forme de réponses API, enrichissant ainsi la fonctionnalité des applications ASP.NET. En adoptant les normes OpenAPI et en tirant parti des fonctions robustes d'IronPDF, les développeurs peuvent améliorer leurs pratiques en matière de documentation des API et proposer aux utilisateurs des applications perfectionnées et riches en fonctionnalités.

Pour des informations détaillées sur les licences d'IronPDF, veuillez vous référer à la page d'accueil du site webDétails de la licence IronPDF. En outre, vous pouvez explorer notreTutoriel de conversion de HTML en PDF pour plus d'informations.