Icône de message
Passer au contenu du pied de page
  1. IronPDF
  2. Blog IronPDF
  3. .NET Aide
  4. OpenAPI .NET
.NET AIDE

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

Curtis Chau
Curtis Chau
Mis à jour:

OpenAPI, anciennement connu sous le nom de Swagger, est une spécification pour construire et décrire des API RESTful. Il permet aux développeurs de définir la structure de leurs API dans un format standardisé, permettant à divers outils et services de comprendre et d'interagir efficacement avec l'API REST et de fournir des commentaires. Dans l'écosystème .NET, l'intégration 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 apprendre les spécifications de support d'OpenAPI et comment créer un fichier PDF à l'aide d'IronPDF et le renvoyer comme réponse à un appel API.

Configuration d'OpenAPI dans .NET

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

Étape 1 : Installer Swashbuckle

Tout d'abord, vous devez installer le package Swashbuckle.AspNetCore via NuGet dans Visual Studio. Vous pouvez le faire en utilisant la console du gestionnaire de packages NuGet :

Install-Package Swashbuckle.AspNetCore

Ou en utilisant l'interface de ligne de commande .NET :

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

Étape 2 : Configurer Swashbuckle

Ensuite, vous devez configurer Swashbuckle dans votre projet ASP.NET Core. Cela implique de mettre à jour le fichier Program.cs pour ajouter des services Swagger et configurer le middleware 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

Génération et visualisation de la documentation API

Une fois que Swashbuckle est configuré, l'exécution de votre application générera automatiquement la documentation OpenAPI. Vous pouvez visualiser ces descriptions OpenAPI en naviguant vers l'interface utilisateur Swagger.

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 des API, et assurer la cohérence entre différents services. La spécification OpenAPI définit une interface standard, indépendante de la langue, pour les API, permettant à la fois aux humains et aux ordinateurs de comprendre les capacités d'un service sans accès au code source.

Extension d'OpenAPI avec des annotations personnalisées

Swashbuckle vous permet d'améliorer 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 de l'API et les structures de données.

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

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 de terminaison.

Résultat

OpenAPI .NET (Comment cela fonctionne pour les développeurs) : Figure 1 - Résultat des annotations personnalisées

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

OpenAPI .NET (Comment cela fonctionne pour les développeurs) : Figure 2 - Résultat de la réponse

IronPDF

IronPDF pour ASP.NET est un outil puissant qui permet la génération et la manipulation transparentes de documents PDF au sein d'applications ASP.NET. Avec son API intuitive et sa fonctionnalité robuste, les développeurs peuvent intégrer sans effort la génération de PDF dans leurs projets web, offrant aux utilisateurs des capacités de gestion de documents améliorées. Que ce soit pour créer des PDFs à partir de zéro, convertir du contenu HTML en PDF, ou ajouter des éléments dynamiques comme des images et du texte, IronPDF simplifie le processus, assurant une génération de documents efficace et professionnelle.

Étapes pour installer à l'aide du gestionnaire de packages NuGet :

  1. Ouvrez votre projet ASP.NET dans Visual Studio et accédez au menu "Outils".
  2. Sélectionnez "Gestionnaire de package NuGet" puis cliquez sur "Gérer les packages NuGet pour la solution".
  3. Dans l'onglet "Parcourir", recherchez "IronPDF" et sélectionnez la version désirée. Cliquez sur "Installer" pour ajouter le package à votre projet. IronPDF et ses dépendances seront automatiquement téléchargés et intégrés, vous permettant de commencer à utiliser ses fonctionnalités dans votre application ASP.NET sans problème.

OpenAPI .NET (Comment cela fonctionne pour les développeurs) : Figure 3 - IronPDF

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

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

            // 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 (Comment cela fonctionne pour les développeurs) : Figure 4 - Résultat API

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

OpenAPI .NET (Comment cela fonctionne pour les développeurs) : Figure 5 - Résultat PDF

Conclusion

OpenAPI, anciennement connu sous le nom de Swagger, simplifie la conception et la documentation des API RESTful dans l'écosystème .NET via des bibliothèques telles que Swashbuckle, facilitant la génération automatique de documentation API pour les projets ASP.NET Core. En démontrant la synergie entre OpenAPI et IronPDF, nous avons montré comment utiliser les capacités d'IronPDF pour générer des fichiers PDF à partir de contenu HTML et les renvoyer comme réponses API, enrichissant la fonctionnalité des applications ASP.NET. En adoptant les normes OpenAPI et en tirant parti des fonctionnalités robustes d'IronPDF, les développeurs peuvent améliorer leurs pratiques de documentation API et offrir aux utilisateurs des applications soignées et riches en fonctionnalités.

Pour des informations détaillées sur la licence IronPDF, veuillez vous référer aux détails de licence IronPDF. De plus, vous pouvez explorer notre didacticiel de conversion HTML en PDF pour plus de conseils.

Questions Fréquemment Posées

Comment puis-je convertir du contenu HTML en PDF dans une application ASP.NET ?

Vous pouvez utiliser IronPDF dans une application ASP.NET pour convertir du contenu HTML en PDF. En tirant parti des capacités de IronPDF, vous pouvez rendre des chaînes ou des fichiers HTML en documents PDF, qui peuvent ensuite être servis en tant que réponses d'API ou enregistrés à des fins de gestion de documents.

Quel est le rôle d'OpenAPI dans l'écosystème .NET ?

OpenAPI joue un rôle crucial dans l'écosystème .NET en fournissant un moyen standardisé de définir et documenter les API RESTful. Cette intégration est souvent facilitée par des outils tels que Swashbuckle, qui aide à générer des spécifications OpenAPI et permet une consommation facile des API au sein des projets ASP.NET Core.

Comment configurer Swagger UI dans un projet .NET à l'aide de Swashbuckle ?

Pour configurer Swagger UI dans un projet .NET à l'aide de Swashbuckle, installez le package Swashbuckle.AspNetCore via NuGet. Ensuite, configurez les services Swagger dans votre fichier Program.cs et configurez le middleware Swagger pour activer la génération et l'accès automatiques de la documentation de l'API via Swagger UI.

Comment puis-je générer des SDK client à partir des définitions OpenAPI dans .NET ?

Les définitions OpenAPI peuvent être utilisées pour générer des SDK client, qui facilitent la consommation des API en abstraisant la complexité des appels d'API. Dans .NET, des outils tels que Swashbuckle peuvent générer ces définitions, qui peuvent ensuite être utilisées avec des outils comme AutoRest pour créer des SDK client dans divers langages de programmation.

Quels sont les avantages de l'utilisation d'annotations personnalisées dans la documentation OpenAPI ?

Les annotations personnalisées dans la documentation OpenAPI améliorent la clarté et le détail des spécifications d'API. Dans .NET, Swashbuckle vous permet d'utiliser des attributs tels que SwaggerOperation et SwaggerResponse pour ajouter des descriptions et des codes de réponse, rendant ainsi la documentation de l'API plus informative et plus facile à comprendre pour les développeurs.

Comment puis-je livrer un fichier PDF comme réponse d'API dans ASP.NET Core ?

Vous pouvez livrer un fichier PDF comme réponse d'API dans ASP.NET Core en utilisant IronPDF. Générez le PDF à partir du contenu HTML à l'aide des méthodes de rendu de IronPDF, et retournez le fichier PDF dans votre action de contrôleur d'API en utilisant IActionResult de ASP.NET Core pour sortir le fichier dans le cadre de la réponse.

Quels avantages l'association des outils OpenAPI et de génération de PDF apporte-t-elle aux applications ASP.NET ?

L'association des outils OpenAPI et de génération de PDF tels que IronPDF dans les applications ASP.NET fournit une documentation API complète et améliore la fonctionnalité en permettant aux API de retourner des documents PDF professionnels. Cette intégration favorise une gestion efficace des documents et enrichit les capacités globales de l'application.

Curtis Chau
Curtis Chau
  Discutez maintenant avec l'équipe d'ingénierie
Rédacteur technique

Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes ...

Lire la suite

Articles connexes

Essai de 30 jours → Produit complet. Pas de limites. Pas de carte. Démarrer l'essai gratuit