Knife4j est un outil d'amélioration de la documentation d'API qui s'appuie sur Swagger. Il offre une interface utilisateur plus attrayante et des fonctionnalités supplémentaires par rapport à la version native de Swagger UI, notamment :

• Groupement des endpoints
• Tri des endpoints
• Exportation de la documentation hors ligne
• Support du débogage d'endpoints
• Interface utilisateur conviviale, notamment en chinois

Le package IGeekFan.AspNetCore.Knife4jUI permet d'intégrer facilement Knife4j UI dans les appplications ASP.NET Core, remplaçant ainsi la page Swagger UI par défaut.

Installation

Pour commencer, installez les packages NuGet nécessaires. Vous aurez besoin de Swashbuckle.AspNetCore pour générer le fichier JSON de spécification OpenAPI.

dotnet add package IGeekFan.AspNetCore.Knife4jUI
dotnet add package Swashbuckle.AspNetCore

Configuration

Modifiez votre fichier Program.cs pour enregistrer les services Knife4j et Swagger.

var builder = WebApplication.CreateBuilder(args);

// Ajouter les services Swagger et Knife4j UI
builder.Services.AddSwaggerGen(options =>
{
   options.SwaggerDoc("v1", new OpenApiInfo { Title = "API V1", Version = "v1" });

   // Définir un serveur (facultatif)
   options.AddServer(new OpenApiServer()
   {
       Url = "", // Laissez vide pour le serveur local par défaut
       Description = "Serveur local"
   });

   // Personnaliser les IDs des opérations pour une meilleure lisibilité
   options.CustomOperationIds(apiDesc =>
   {
       var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
       if (controllerAction != null)
       {
           return $"{controllerAction.ControllerName}-{controllerAction.ActionName}";
       }
       return null;
   });
});

var app = builder.Build();

// Activer les middlewares
if (app.Environment.IsDevelopment())
{
   app.UseSwagger(); // Nécessaire pour générer le JSON Swagger

   // Remplacer UseSwaggerUI() par UseKnife4jUI()
   app.UseKnife4jUI(options =>
   {
       options.RoutePrefix = ""; // Servir l'interface à la racine
       options.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");
   });
}

app.MapControllers();
app.Run();

Note : Si vous utilisiez précédemment app.UseSwaggerUI(), assurez-vous de le remplacer par app.UseKnife4jUI().

Activation des commentaires XML (Facultatif)

Pour que les descriptions des endpoints et des paramètres s'affichent dans Knife4j, vous devez activer la génération de commentaires XML.

Modification du fichier projet (.csproj)

Ajoutez la configuration suivante à votre fichier .csproj :

<PropertyGroup>
 <GenerateDocumentationFile>true</GenerateDocumentationFile>
 <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Configuration du chemin des commentaires XML dans Program.cs

Dans la configuration de AddSwaggerGen, incluez les commentaires XML :

builder.Services.AddSwaggerGen(options =>
{
   // ... autres configurations SwaggerGen

   var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
   options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

N'oubliez pas d'ajouter des comentaires XML à vos contrôleurs et méthodes pour une documentation complète.

/// <summary>
/// Service de prévisions météorologiques.
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
   private static readonly string[] Summaries = new[]
   {
       "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
   };

   /// <summary>
   /// Récupère la liste des prévisions météorologiques.
   /// </summary>
   /// <returns>Une énumération de prévisions météorologiques.</returns>
   [HttpGet(Name = "GetWeatherForecast")]
   public IEnumerable<WeatherForecast> Get()
   {
       return Enumerable.Range(1, 5).Select(index => new WeatherForecast
       {
           Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
           TemperatureC = Random.Shared.Next(-20, 55),
           Summary = Summaries[Random.Shared.Next(Summaries.Length)]
       })
       .ToArray();
   }
}

Accès à l'interface Knife4j UI

Une fois votre application lancée, accédez à l'interface utilisateur de Knife4j dans votre navigateur à l'adresse suivante :

http://localhost:<port>

Vous découvrirez une interface de documentation d'API améliorée.