.NET AIDE

Swashbuckle ASP .NET Core (Comment cela fonctionne pour les développeurs)

Mis à jour:juillet 28, 2025

Swashbuckle is a C# .NET Core NuGet package that helps to automatically document RESTful Web APIs. In this blog, we are going to explore the Swashbuckle ASP.NET Core and IronPDF Installation Instructions NuGet packages, enabling the modern development of ASP.NET Core Web APIs. Together, they provide a host of functionalities that can be achieved with minimal code.

Les pages de documentation de l'API sont affichées à l'aide de l'outil Swagger UI, qui utilise un fichier swagger.json généré à partir du projet Web API. Le document JSON généré suit la norme Open API. Swashbuckle est disponible en tant que package NuGet Swashbuckle.AspNetCore, qui, une fois installé et configuré, exposera automatiquement le Swagger JSON. L'outil Swagger UI lit le fichier Swagger JSON, généré à partir des commentaires XML écrits sur les API. De plus, un fichier de documentation XML peut être créé en l'activant dans le fichier de paramètres du projet. Les commentaires XML sont convertis en un fichier de documentation XML, à partir duquel le Swagger JSON est généré. Ensuite, le middleware Swagger lit le JSON et expose les points de terminaison du Swagger JSON.

Implémentation dans le projet .NET Core Web API

Commençons par un projet Web API :

dotnet new webapi -n SwashbuckleDemo
cd SwashbuckleDemo
dotnet build
dotnet add package Swashbuckle.AspNetCore --version 6.5.0
dotnet build

dotnet new webapi -n SwashbuckleDemo
cd SwashbuckleDemo
dotnet build
dotnet add package Swashbuckle.AspNetCore --version 6.5.0
dotnet build

SHELL

Ici, nous créons un projet web API nommé "SwashbuckleDemo" puis installons le package Swashbuckle dans le projet .NET Core Web API en utilisant la console du gestionnaire de packages.

Configurer le middleware Swagger

Configurer les services Swagger dans le fichier Startup.cs.

using System.Reflection;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Other service configurations...

        // Register the Swagger generator
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

            // Optionally, include XML comments for additional information
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        // Other app configurations...

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable Swagger UI (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }
}

using System.Reflection;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Other service configurations...

        // Register the Swagger generator
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

            // Optionally, include XML comments for additional information
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        // Other app configurations...

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable Swagger UI (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }
}

Imports System.Reflection
Imports Microsoft.Extensions.DependencyInjection
Imports Microsoft.AspNetCore.Builder

Public Class Startup
	Public Sub ConfigureServices(ByVal services As IServiceCollection)
		' Other service configurations...

		' Register the Swagger generator
		services.AddSwaggerGen(Sub(c)
			c.SwaggerDoc("v1", New OpenApiInfo With {
				.Title = "My API",
				.Version = "v1"
			})

			' Optionally, include XML comments for additional information
			Dim xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml"
			Dim xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile)
			c.IncludeXmlComments(xmlPath)
		End Sub)
	End Sub

	Public Sub Configure(ByVal app As IApplicationBuilder, ByVal env As IHostingEnvironment)
		' Other app configurations...

		' Enable middleware to serve generated Swagger as a JSON endpoint.
		app.UseSwagger()

		' Enable Swagger UI (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
		app.UseSwaggerUI(Sub(c)
			c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1")
		End Sub)
	End Sub
End Class

$vbLabelText $csharpLabel

Ajouter un contrôleur pour les API de liste de choses à faire :

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Builder;
using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

// Example to define an entity class
public class Todo
{
    public int Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

// Example to define a DbContext class
public class TodoDb : DbContext
{
    public DbSet<Todo> Todos => Set<Todo>();
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "SwashbuckleDemo!");

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id) is Todo todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();
    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);
    if (todo is null) return Results.NotFound();
    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.Ok(todo);
    }

    return Results.NotFound();
});

app.Run();

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Builder;
using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

// Example to define an entity class
public class Todo
{
    public int Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

// Example to define a DbContext class
public class TodoDb : DbContext
{
    public DbSet<Todo> Todos => Set<Todo>();
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "SwashbuckleDemo!");

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id) is Todo todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();
    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);
    if (todo is null) return Results.NotFound();
    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.Ok(todo);
    }

    return Results.NotFound();
});

app.Run();

Imports Microsoft.AspNetCore.Http.HttpResults
Imports Microsoft.AspNetCore.Builder
Imports Microsoft.EntityFrameworkCore
Imports Microsoft.AspNetCore.Mvc
Imports System.Threading.Tasks

' Example to define an entity class
Public Class Todo
	Public Property Id() As Integer
	Public Property Name() As String
	Public Property IsComplete() As Boolean
End Class

' Example to define a DbContext class
Public Class TodoDb
	Inherits DbContext

	Public ReadOnly Property Todos() As DbSet(Of Todo)
		Get
			Return [Set](Of Todo)()
		End Get
	End Property
End Class

Private builder = WebApplication.CreateBuilder(args)
Private app = builder.Build()

app.MapGet("/", Function() "SwashbuckleDemo!")

app.MapGet("/todoitems", Async Function(db As TodoDb) Await db.Todos.ToListAsync())

app.MapGet("/todoitems/complete", Async Function(db As TodoDb) Await db.Todos.Where(Function(t) t.IsComplete).ToListAsync())

Dim tempVar As Boolean = TypeOf db.Todos.FindAsync(id) Is Todo
Dim todo As Todo = If(tempVar, CType(db.Todos.FindAsync(id), Todo), Nothing)
app.MapGet("/todoitems/{id}", Async Function(id As Integer, db As TodoDb)If(Await tempVar, Results.Ok(todo), Results.NotFound()))

app.MapPost("/todoitems", Async Function(todo As Todo, db As TodoDb)
	db.Todos.Add(todo)
	Await db.SaveChangesAsync()
	Return Results.Created($"/todoitems/{todo.Id}", todo)
End Function)

app.MapPut("/todoitems/{id}", Async Function(id As Integer, inputTodo As Todo, db As TodoDb)
	Dim todo = Await db.Todos.FindAsync(id)
	If todo Is Nothing Then
		Return Results.NotFound()
	End If
	todo.Name = inputTodo.Name
	todo.IsComplete = inputTodo.IsComplete
	Await db.SaveChangesAsync()
	Return Results.NoContent()
End Function)

app.MapDelete("/todoitems/{id}", Async Function(id As Integer, db As TodoDb)
	Dim tempVar2 As Boolean = TypeOf db.Todos.FindAsync(id) Is Todo
	Dim todo As Todo = If(tempVar2, CType(db.Todos.FindAsync(id), Todo), Nothing)
	If Await tempVar2 Then
		db.Todos.Remove(todo)
		Await db.SaveChangesAsync()
		Return Results.Ok(todo)
	End If

	Return Results.NotFound()
End Function)

app.Run()

$vbLabelText $csharpLabel

Un contrôleur peut également être ajouté comme ci-dessous :

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System;
using System.Linq;

namespace RestFullMinimalApi.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;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        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();
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }
    }
}

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System;
using System.Linq;

namespace RestFullMinimalApi.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;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        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();
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }
    }
}

Imports Microsoft.AspNetCore.Mvc
Imports Microsoft.Extensions.Logging
Imports System.Collections.Generic
Imports System
Imports System.Linq

Namespace RestFullMinimalApi.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

		''' <summary>
		''' Retrieves WeatherForecast
		''' </summary>
		''' <remarks>Awesomeness!</remarks>
		''' <response code="200">Retrieved</response>
		''' <response code="404">Not found</response>
		''' <response code="500">Oops! Can't lookup your request right now</response>
		<HttpGet(Name := "GetWeatherForecast")>
		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

	Public Class WeatherForecast
		Public Property [Date]() As DateTime
		Public Property TemperatureC() As Integer
		Public Property Summary() As String
	End Class
End Namespace

$vbLabelText $csharpLabel

Le code ci-dessus est disponible sur GitHub - Swashbuckle Demo.

Swashbuckle offre les fonctionnalités suivantes

Outil Swagger UI

Swashbuckle ASP .NET Core (Comment ça marche pour le développeur) : Figure 1 - Outil Swagger UI

Swagger UI est disponible à "/swagger/index.html" à partir de l'URL de base de l'application Web API. Il répertorie toutes les APIs REST à partir du code. Le générateur Swagger lit le fichier JSON et remplit l'interface.

Swagger JSON

Swashbuckle.AspNetCore génère automatiquement le fichier Swagger JSON, qui contient des informations sur la structure de l'API, y compris des détails tels que les points de terminaison, les types de requêtes et de réponses, et plus encore. Ce fichier JSON peut être utilisé par d'autres outils et services qui prennent en charge la norme Swagger/OpenAPI.

Le fichier Swagger JSON est disponible à "/swagger/v1/swagger.json" à partir de l'URL de base de l'application web API.

Swashbuckle ASP .NET Core (Comment ça marche pour le développeur) : Figure 2 - Le fichier swagger JSON.

Anotations de code

Les développeurs peuvent utiliser les commentaires XML et les attributs au sein de leurs contrôleurs Core ASP.NET pour fournir des informations supplémentaires pour la documentation Swagger. Cela inclut les descriptions, les exemples et d'autres métadonnées qui améliorent la documentation Swagger générée.

[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;
    }

    /// <summary>
    /// Retrieves WeatherForecast
    /// </summary>
    /// <remarks>Awesomeness!</remarks>
    /// <response code="200">Retrieved</response>
    /// <response code="404">Not found</response>
    /// <response code="500">Oops! Can't lookup your request right now</response>
    [HttpGet(Name = "GetWeatherForecast")]
    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();
    }
}

[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;
    }

    /// <summary>
    /// Retrieves WeatherForecast
    /// </summary>
    /// <remarks>Awesomeness!</remarks>
    /// <response code="200">Retrieved</response>
    /// <response code="404">Not found</response>
    /// <response code="500">Oops! Can't lookup your request right now</response>
    [HttpGet(Name = "GetWeatherForecast")]
    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();
    }
}

<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

	''' <summary>
	''' Retrieves WeatherForecast
	''' </summary>
	''' <remarks>Awesomeness!</remarks>
	''' <response code="200">Retrieved</response>
	''' <response code="404">Not found</response>
	''' <response code="500">Oops! Can't lookup your request right now</response>
	<HttpGet(Name := "GetWeatherForecast")>
	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

$vbLabelText $csharpLabel

Options de configuration

Swashbuckle.AspNetCore fournit diverses options de configuration pour personnaliser la génération de la documentation Swagger. Les développeurs peuvent contrôler quelles APIs sont documentées, configurer les conventions de nommage, et ajuster d'autres paramètres.

Voici quelques-unes des principales options de configuration fournies par Swashbuckle.AspNetCore :

Options SwaggerGen

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

c.SwaggerDoc("v1", New OpenApiInfo With {
	.Title = "My API",
	.Version = "v1"
})

$vbLabelText $csharpLabel

Cette ligne spécifie la version du document Swagger et inclut des métadonnées telles que le titre et la version de votre API.

c.IncludeXmlComments(xmlPath);

c.IncludeXmlComments(xmlPath);

c.IncludeXmlComments(xmlPath)

$vbLabelText $csharpLabel

Cette option vous permet d'inclure les commentaires XML de votre code pour fournir des informations supplémentaires dans la documentation Swagger. La variable xmlPath doit pointer vers l'emplacement de votre fichier de commentaires XML.

c.DescribeAllParametersInCamelCase();

c.DescribeAllParametersInCamelCase();

c.DescribeAllParametersInCamelCase()

$vbLabelText $csharpLabel

Cette option configure le générateur Swagger pour utiliser camelCase pour les noms de paramètres.

c.OperationFilter<CustomOperationFilter>();

c.OperationFilter<CustomOperationFilter>();

c.OperationFilter(Of CustomOperationFilter)()

$vbLabelText $csharpLabel

Vous pouvez enregistrer des filtres d'opération personnalisés pour modifier la documentation Swagger pour des opérations spécifiques. CustomOperationFilter est une classe qui implémente IOperationFilter.

Options Swagger UI

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1")

$vbLabelText $csharpLabel

Cette ligne configure Swagger UI pour afficher la documentation. Le premier paramètre est l'URL du fichier Swagger JSON, et le deuxième paramètre est un nom convivial pour la version de l'API.

c.RoutePrefix = "swagger";

c.RoutePrefix = "swagger";

c.RoutePrefix = "swagger"

$vbLabelText $csharpLabel

Vous pouvez définir le préfixe de route pour Swagger UI. Dans cet exemple, Swagger UI sera disponible à /swagger.

c.DocExpansion(DocExpansion.None);

c.DocExpansion(DocExpansion.None);

c.DocExpansion(DocExpansion.None)

$vbLabelText $csharpLabel

Cette option contrôle comment Swagger UI affiche la documentation de l'API. DocExpansion.None replie toutes les opérations par défaut.

Options Swagger

c.SerializeAsV2 = true;

c.SerializeAsV2 = true;

c.SerializeAsV2 = True

$vbLabelText $csharpLabel

Cette option spécifie s'il faut sérialiser le document Swagger au format de version 2.0 (true) ou 3.0 (false). Réglez-le sur true si vous voulez utiliser Swagger 2.0.

c.DisplayOperationId();

c.DisplayOperationId();

c.DisplayOperationId()

$vbLabelText $csharpLabel

Cette option affiche l'ID d'opération dans Swagger UI, ce qui peut être utile pour le débogage et la compréhension de la structure de votre API.

c.OAuthClientId("swagger-ui");

c.OAuthClientId("swagger-ui");

c.OAuthClientId("swagger-ui")

$vbLabelText $csharpLabel

Si votre API utilise l'authentification OAuth, vous pouvez configurer l'ID client OAuth pour Swagger UI.

Ce ne sont que quelques exemples des options de configuration disponibles. La bibliothèque Swashbuckle.AspNetCore est hautement personnalisable, et vous pouvez adapter la documentation Swagger pour répondre à vos besoins spécifiques en combinant diverses options et filtres. Référez-vous toujours à la documentation officielle ou à IntelliSense dans votre environnement de développement pour obtenir les informations les plus à jour et complètes sur les options disponibles.

Introducing IronPDF

IronPDF Product Overview is the C# PDF Library from site Web Iron Software qui aide à lire et générer des documents PDF. Il peut facilement convertir des documents formatés avec des informations de style en PDF. IronPDF peut générer sans effort des PDFs à partir de contenu HTML. Il peut télécharger le contenu HTML d'une URL puis générer des PDFs.

IronPDF est un excellent outil pour convertir des pages web, des URLs, et HTML en PDF qui répliquent parfaitement la source. Il est idéal pour générer des PDFs de contenu en ligne tel que des rapports et des factures, et crée sans effort des versions PDF de toute page web.

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

Imports IronPdf

Friend Class Program
	Shared Sub Main(ByVal args() As String)
		Dim renderer = New ChromePdfRenderer()

		' 1. Convert HTML String to PDF
		Dim htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>"
		Dim pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent)
		pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf")

		' 2. Convert HTML File to PDF
		Dim htmlFilePath = "path_to_your_html_file.html" ' Specify the path to your HTML file
		Dim pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath)
		pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf")

		' 3. Convert URL to PDF
		Dim url = "http://ironpdf.com" ' Specify the URL
		Dim pdfFromUrl = renderer.RenderUrlAsPdf(url)
		pdfFromUrl.SaveAs("URLToPDF.pdf")
	End Sub
End Class

$vbLabelText $csharpLabel

Installation

Install IronPDF via NuGet using the NuGet Package Manager Details or the Visual Studio Installation Guide.

Dans la console du gestionnaire de packages, entrez la commande :

Install-Package IronPdf

Utilisation de Visual Studio

Maintenant, modifions notre application pour ajouter la fonctionnalité de téléchargement de contenu de site Web en tant que fichier PDF.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using IronPdf;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

namespace RestFullMinimalApi.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;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        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();
        }

        /// <summary>
        /// Retrieves WeatherForecast as Pdf
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet("download", Name = "DownloadWeatherForecast")]
        public IActionResult GetWeatherPdf()
        {
            var results = 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();

            var html = GetHtml(results);
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf(html);
            var fileName = "WeatherReport.pdf";
            pdf.SaveAs(fileName);

            var stream = new FileStream(fileName, FileMode.Open);
            // Return the PDF file for download
            return new FileStreamResult(stream, "application/octet-stream") { FileDownloadName = fileName };
        }

        private static string GetHtml(WeatherForecast[] weatherForecasts)
        {
            string header = @"
<html>
<head><title>WeatherForecast</title></head>
<body>
<h1>WeatherForecast</h1>
";

            var footer = @"
</body>
</html>";

            var htmlContent = header;
            foreach (var weather in weatherForecasts)
            {
                htmlContent += $@"
    <h2>{weather.Date}</h2>
    <p>Summary: {weather.Summary}</p>
    <p>Temperature in Celsius: {weather.TemperatureC}</p>
    <p>Temperature in Fahrenheit: {weather.TemperatureF}</p>
";
            }
            htmlContent += footer;
            return htmlContent;
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }

        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using IronPdf;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

namespace RestFullMinimalApi.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;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        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();
        }

        /// <summary>
        /// Retrieves WeatherForecast as Pdf
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet("download", Name = "DownloadWeatherForecast")]
        public IActionResult GetWeatherPdf()
        {
            var results = 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();

            var html = GetHtml(results);
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf(html);
            var fileName = "WeatherReport.pdf";
            pdf.SaveAs(fileName);

            var stream = new FileStream(fileName, FileMode.Open);
            // Return the PDF file for download
            return new FileStreamResult(stream, "application/octet-stream") { FileDownloadName = fileName };
        }

        private static string GetHtml(WeatherForecast[] weatherForecasts)
        {
            string header = @"
<html>
<head><title>WeatherForecast</title></head>
<body>
<h1>WeatherForecast</h1>
";

            var footer = @"
</body>
</html>";

            var htmlContent = header;
            foreach (var weather in weatherForecasts)
            {
                htmlContent += $@"
    <h2>{weather.Date}</h2>
    <p>Summary: {weather.Summary}</p>
    <p>Temperature in Celsius: {weather.TemperatureC}</p>
    <p>Temperature in Fahrenheit: {weather.TemperatureF}</p>
";
            }
            htmlContent += footer;
            return htmlContent;
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }

        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

Imports Microsoft.AspNetCore.Mvc
Imports Microsoft.Extensions.Logging
Imports IronPdf
Imports System
Imports System.Collections.Generic
Imports System.IO
Imports System.Linq

Namespace RestFullMinimalApi.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

		''' <summary>
		''' Retrieves WeatherForecast
		''' </summary>
		''' <remarks>Awesomeness!</remarks>
		''' <response code="200">Retrieved</response>
		''' <response code="404">Not found</response>
		''' <response code="500">Oops! Can't lookup your request right now</response>
		<HttpGet(Name := "GetWeatherForecast")>
		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

		''' <summary>
		''' Retrieves WeatherForecast as Pdf
		''' </summary>
		''' <remarks>Awesomeness!</remarks>
		''' <response code="200">Retrieved</response>
		''' <response code="404">Not found</response>
		''' <response code="500">Oops! Can't lookup your request right now</response>
		<HttpGet("download", Name := "DownloadWeatherForecast")>
		Public Function GetWeatherPdf() As IActionResult
			Dim results = 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()

			Dim html = GetHtml(results)
			Dim renderer = New ChromePdfRenderer()
			Dim pdf = renderer.RenderHtmlAsPdf(html)
			Dim fileName = "WeatherReport.pdf"
			pdf.SaveAs(fileName)

			Dim stream = New FileStream(fileName, FileMode.Open)
			' Return the PDF file for download
			Return New FileStreamResult(stream, "application/octet-stream") With {.FileDownloadName = fileName}
		End Function

		Private Shared Function GetHtml(ByVal weatherForecasts() As WeatherForecast) As String
			Dim header As String = "
<html>
<head><title>WeatherForecast</title></head>
<body>
<h1>WeatherForecast</h1>
"

			Dim footer = "
</body>
</html>"

			Dim htmlContent = header
			For Each weather In weatherForecasts
				htmlContent &= $"
    <h2>{weather.Date}</h2>
    <p>Summary: {weather.Summary}</p>
    <p>Temperature in Celsius: {weather.TemperatureC}</p>
    <p>Temperature in Fahrenheit: {weather.TemperatureF}</p>
"
			Next weather
			htmlContent &= footer
			Return htmlContent
		End Function
	End Class

	Public Class WeatherForecast
		Public Property [Date]() As DateTime
		Public Property TemperatureC() As Integer
		Public Property Summary() As String

		Public ReadOnly Property TemperatureF() As Integer
			Get
				Return 32 + CInt(Math.Truncate(TemperatureC / 0.5556))
			End Get
		End Property
	End Class
End Namespace

$vbLabelText $csharpLabel

Ici, nous utilisons les données météorologiques pour générer une chaîne HTML, qui est ensuite utilisée pour créer un document PDF.

Contenu HTML

Swashbuckle ASP .NET Core (Comment ça marche pour le développeur) : Figure 4 - Contenu HTML pour Prévisions Météo.

Et le rapport PDF ressemble à ceci :

Swashbuckle ASP .NET Core (Comment ça marche pour le développeur) : Figure 5 - Fichier de sortie HTML en PDF : WeatherReport.pdf

Tout le code peut être trouvé sur GitHub - Code source Demo Swashbuckle.
Le document a un petit filigrane pour les licences d'essai, amovible avec une licence valide.

Licence (essai gratuit disponible)

Pour que le code ci-dessus fonctionne, une clé de licence est requise. Placez cette clé dans le fichier appsettings.json.

{
    "IronPdf": {
        "LicenseKey": "your license key"
    }
}

Une licence d'essai est disponible pour les développeurs lors de l'enregistrement avec Inscription d'essai IronPDF. Aucune carte de crédit n'est nécessaire pour une licence d'essai. Inscrivez-vous avec votre adresse e-mail pour obtenir un essai gratuit.

Conclusion

Comprendre Swashbuckle et IronPDF vous permet d'intégrer efficacement les capacités de documentation de l'API et de génération de PDF dans vos applications ASP.NET Core. IronPDF also offers comprehensive documentation for Getting Started, along with various Code Examples for PDF Generation.

De plus, vous pouvez explorer les produits logiciels connexes d'Iron Software qui vous aideront à améliorer vos compétences en codage et à répondre aux exigences des applications modernes.

Questions Fréquemment Posées

Comment puis-je documenter les API Web RESTful en utilisant Swashbuckle dans ASP.NET Core ?

Swashbuckle peut être utilisé pour documenter les API Web RESTful en générant une documentation Swagger à partir de commentaires XML dans le code. Vous devez installer le package Swashbuckle.AspNetCore et le configurer dans le fichier `Startup.cs` de votre projet ASP.NET Core.

Quelles étapes sont impliquées dans la mise en place de Swashbuckle pour un nouveau projet Web API ASP.NET Core ?

Pour configurer Swashbuckle, commencez par installer le package NuGet Swashbuckle.AspNetCore. Ensuite, configurez le middleware Swagger dans le fichier `Startup.cs` en ajoutant `services.AddSwaggerGen()` dans la méthode `ConfigureServices` et `app.UseSwagger()` avec `app.UseSwaggerUI()` dans la méthode `Configure`.

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

Vous pouvez convertir du contenu HTML en PDF dans une application .NET Core en utilisant IronPDF. Cette bibliothèque permet de convertir des chaînes HTML, des fichiers et des URLs en documents PDF à l'aide de méthodes telles que `RenderHtmlAsPdf` et `RenderUrlAsPdf`.

Quels sont les avantages d'utiliser Swashbuckle dans le développement d'API ?

Swashbuckle simplifie la documentation des API en générant automatiquement une documentation conforme à Swagger, ce qui aide à maintenir des normes de documentation claires et cohérentes. Il propose également une interface conviviale pour explorer et tester les API via Swagger UI.

Comment puis-je intégrer des capacités de génération de PDF dans un projet ASP.NET Core ?

L'intégration de la génération de PDF dans un projet ASP.NET Core peut être réalisée en utilisant IronPDF. Installez la bibliothèque IronPDF via NuGet et utilisez ses méthodes pour générer des PDF à partir de divers types de contenu. Assurez-vous que votre projet inclut les directives d'utilisation nécessaires et les clés de licence éventuelles.

Quelles options de configuration sont disponibles pour personnaliser la documentation Swagger dans Swashbuckle ?

Swashbuckle offre diverses options de configuration pour personnaliser la documentation Swagger, notamment la définition de la gestion des versions de l'API, l'activation des commentaires XML, la définition des conventions de nommage des paramètres et la personnalisation de l'apparence et du comportement de l'interface utilisateur Swagger.

Comment puis-je résoudre les problèmes courants lors de l'utilisation de Swashbuckle dans un projet ASP.NET Core ?

Les problèmes courants avec Swashbuckle peuvent être résolus en s'assurant que la documentation XML est activée dans les propriétés du projet, en vérifiant les versions correctes des packages et en vérifiant la configuration correcte dans le fichier `Startup.cs`, y compris le bon ordre des middlewares.

Quelles sont certaines des fonctionnalités d'IronPDF pour la génération de PDFs en C# ?

IronPDF propose des fonctionnalités telles que la conversion de HTML, d'URLs et de contenu ASP.NET en PDF, l'ajout d'en-têtes et de pieds de page, la fusion de PDFs et la manipulation de fichiers PDF existants. Il s'agit d'une bibliothèque complète pour la gestion des opérations PDF dans des projets C#.

Comment IronPDF prend-il en charge la licence pour un usage commercial ?

IronPDF prend en charge la licence grâce à une clé de licence commerciale. Vous pouvez essayer IronPDF avec un essai gratuit et inclure la clé de licence dans la configuration de votre projet, généralement dans le fichier `appsettings.json` sous la section `IronPdf`.

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

Articles connexes

Mis à jourseptembre 4, 2025

RandomNumberGenerator C#

L'utilisation de la classe RandomNumberGenerator C# peut aider à porter vos projets de génération et d'édition de PDF à un niveau supérieur

Mis à jourseptembre 4, 2025

C# String Equals (Comment ça fonctionne pour les développeurs)

Lorsqu'il est combiné avec une bibliothèque PDF puissante comme IronPDF, la correspondance de modèle de switch permet de construire une logique plus intelligente et plus propre pour le traitement de documents

Mise en avant Client:

Projecteur sur les Développeurs:

Webinaires:

Swashbuckle ASP .NET Core (Comment cela fonctionne pour les développeurs)

Implémentation dans le projet .NET Core Web API

Configurer le middleware Swagger

Swashbuckle offre les fonctionnalités suivantes

Outil Swagger UI

Swagger JSON

Anotations de code

Options de configuration

Options SwaggerGen

Options Swagger UI

Options Swagger

Introducing IronPDF

Installation

Contenu HTML

Licence (essai gratuit disponible)

Conclusion

Questions Fréquemment Posées

Comment puis-je documenter les API Web RESTful en utilisant Swashbuckle dans ASP.NET Core ?

Quelles étapes sont impliquées dans la mise en place de Swashbuckle pour un nouveau projet Web API ASP.NET Core ?

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

Quels sont les avantages d'utiliser Swashbuckle dans le développement d'API ?

Comment puis-je intégrer des capacités de génération de PDF dans un projet ASP.NET Core ?

Quelles options de configuration sont disponibles pour personnaliser la documentation Swagger dans Swashbuckle ?

Comment puis-je résoudre les problèmes courants lors de l'utilisation de Swashbuckle dans un projet ASP.NET Core ?

Quelles sont certaines des fonctionnalités d'IronPDF pour la génération de PDFs en C# ?

Comment IronPDF prend-il en charge la licence pour un usage commercial ?

Swashbuckle ASP .NET Core (Comment cela fonctionne pour les développeurs)

Implémentation dans le projet .NET Core Web API

Configurer le middleware Swagger

Swashbuckle offre les fonctionnalités suivantes

Outil Swagger UI

Swagger JSON

Anotations de code

Options de configuration

Options SwaggerGen

Options Swagger UI

Options Swagger

Introducing IronPDF

Installation

Contenu HTML

Licence (essai gratuit disponible)

Conclusion

Questions Fréquemment Posées

Comment puis-je documenter les API Web RESTful en utilisant Swashbuckle dans ASP.NET Core ?

Quelles étapes sont impliquées dans la mise en place de Swashbuckle pour un nouveau projet Web API ASP.NET Core ?

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

Quels sont les avantages d'utiliser Swashbuckle dans le développement d'API ?

Comment puis-je intégrer des capacités de génération de PDF dans un projet ASP.NET Core ?

Quelles options de configuration sont disponibles pour personnaliser la documentation Swagger dans Swashbuckle ?

Comment puis-je résoudre les problèmes courants lors de l'utilisation de Swashbuckle dans un projet ASP.NET Core ?

Quelles sont certaines des fonctionnalités d'IronPDF pour la génération de PDFs en C# ?

Comment IronPDF prend-il en charge la licence pour un usage commercial ?

Articles connexes

RandomNumberGenerator C#

C# String Equals (Comment ça fonctionne pour les développeurs)

C# Switch Pattern Matching (Comment ça fonctionne pour les développeurs)

Étape suivante : Commencer l'essai gratuit de 30 jours

Étape suivante : Commencer l'essai gratuit de 30 jours

De confiance par plus de 2 millions d'ingénieurs dans le monde entier