Swagger / OpenAPI

Swagger génère une interface Web qui liste les actions des contrôleurs et permet de tester les API HTTP. Lagoon expose ce câblage via le serveur ASP.NET Core et Swashbuckle.

Câblage disponible dans Lagoon

Élément	Rôle
RegisterSwaggerService(services)	Enregistre la génération OpenAPI et configure Swagger UI.
options.AddSwaggerAccess()	Ajoute un client d'authentification pour Swagger UI.
app.UseSwagger()	Active les documents OpenAPI.
app.UseSwaggerUI()	Active l'interface Swagger.
AuthorizeCheckOperationFilter	Ajoute les réponses 401 / 403 et la sécurité oauth2 sur les opérations protégées.

Le projet serveur Demo ne déclare pas de câblage Swagger spécifique ; le câblage vérifié est celui fourni par le framework serveur Lagoon.

Enregistrement côté serveur

Authentification

Dans OnConfigureAuthentification, ajoutez l'accès Swagger lorsque l'application doit exposer Swagger UI. L'ancienne documentation le limitait au mode DEBUG.

Main.cs

protected override void OnConfigureAuthentification(AuthenticationOptions options)
{
    base.OnConfigureAuthentification(options);

#if DEBUG
    // Autorise Swagger UI à demander un jeton pour l'utilisateur connecté.
    options.AddSwaggerAccess();
#endif
}

Par défaut, AddSwaggerAccess() utilise le client SwaggerUI et la redirection /swagger/oauth2-redirect.html.

Services

Dans OnConfigureServices, appelez RegisterSwaggerService(services).

Main.cs

protected override void OnConfigureServices(IServiceCollection services)
{
#if DEBUG
    // Enregistre les documents OpenAPI et la configuration Swagger UI.
    RegisterSwaggerService(services);
#endif

    Services.Registry.RegisterServices(services);
}

Activation des routes Swagger

Dans OnConfigure, activez Swagger et Swagger UI dans le pipeline ASP.NET Core.

Main.cs

protected override void OnConfigure(IApplicationBuilder app)
{
#if DEBUG
    // Expose les documents OpenAPI et l'interface Swagger.
    app.UseSwagger();
    app.UseSwaggerUI();
#endif

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapLagoonFallback();
    });
}

Documents OpenAPI exposés

RegisterSwaggerService(services) configure les documents suivants :

Document	URL	Contenu
External	/openapi/external.json	API publiques versionnées.
Internal	/openapi/internal.json	API internes, seulement en environnement de développement.

Une route est considérée comme externe lorsque son chemin relatif commence par api/v suivi d'un chiffre de version, par exemple api/v1/countries.

Méthodes externes

Versionnez les routes destinées à être utilisées par d'autres applications, par exemple /api/v1/countries. Les routes non versionnées restent dans le document interne.

Interface Swagger UI

L'interface est disponible à l'URL /swagger ou /swagger/index.html sur la racine d'hébergement de l'application.

Si l'utilisateur est déjà connecté, Swagger UI peut récupérer un jeton via le bouton Authorize. Le client utilisé par défaut est SwaggerUI. L'interface utilise le flux OAuth2 configuré par le framework.

Documentation XML

RegisterSwaggerService(services) inclut les commentaires XML du projet serveur si le fichier XML correspondant à l'assembly existe. Activez la génération de la documentation XML dans les propriétés du projet serveur si les descriptions des actions doivent apparaître dans Swagger UI.

Déclarer une API externe versionnée

CountriesController.cs

[ApiController]
[Route("api/[controller]")]
public class CountriesController : LgControllerBase
{
    private readonly ApplicationDbContext _db;

    public CountriesController(ApplicationDbContext db)
    {
        _db = db;
    }

    /// <summary>
    /// Gets all country names for external applications.
    /// </summary>
    /// <returns>The country names.</returns>
    [AllowAnonymous]
    [HttpGet("/api/v1/countries")]
    public IQueryable<VmCountry> GetNamesV1()
    {
        // Route absolue et versionnée : cette action apparaît dans le document externe.
        return _db.Countries
            .GroupBy(c => c.Name)
            .Select(c => new VmCountry()
            {
                Id = c.First().Id,
                Name = c.First().Name
            })
            .OrderBy(c => c.Name);
    }

    /// <summary>
    /// Gets all country names for the application.
    /// </summary>
    /// <returns>The country names.</returns>
    [Queryable]
    [HttpGet("names")]
    public IQueryable<VmCountry> GetNames()
    {
        // Route relative au contrôleur : cette action reste interne.
        return _db.Countries
            .GroupBy(c => c.Name)
            .Select(c => new VmCountry()
            {
                Id = c.First().Id,
                Name = c.First().Name
            })
            .OrderBy(c => c.Name);
    }
}

Points d'attention

• Pour une API externe, commencez la route par / afin d'éviter une route relative au contrôleur.
• Lorsqu'une méthode externe évolue fonctionnellement, créez une nouvelle version de route au lieu de changer le comportement de la version existante.
• Une correction de bug ne nécessite pas forcément une nouvelle version.