C# Academy · Leçon

Documenter les API versionnées

Exposez la documentation de plusieurs versions d’API.

Documenter les API versionnées est une leçon C# Academy gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage C# Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours C# Academy comprend 4 leçons au total.

Un document par version

Lorsqu’une API possède plusieurs versions, vous souhaitez généralement disposer d’un document OpenAPI distinct pour chaque version, afin que les consommateurs ne voient que les points de terminaison qui les concernent.

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

Le fournisseur de descriptions des versions d’API

Asp.Versioning expose IApiVersionDescriptionProvider, qui répertorie toutes les versions d’API détectées. Parcourez cette liste pour enregistrer un document par version.

var provider = app.Services
    .GetRequiredService<IApiVersionDescriptionProvider>();

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

Enregistrer un document par version

Appelez AddOpenApi une fois par groupe de versions, en nommant chaque document d’après le groupe.

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Filtrer les points de terminaison dans le document approprié

Utilisez un transformateur de document ou le ShouldInclude prédicat afin que chaque document ne contienne que les points de terminaison de sa version, déterminés d’après le nom du groupe.

builder.Services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = description =>
        description.GroupName == "v1";
});

Associer les documents

MapOpenApi, avec le modèle par défaut, publie chaque document nommé à l’adresse /openapi/{documentName}.json.

app.MapOpenApi();
// /openapi/v1.json and /openapi/v2.json both available

Définir les informations propres à chaque document

Donnez à chaque document de version son propre titre et sa propre version dans un transformateur, afin que la documentation se décrive elle-même.

builder.Services.AddOpenApi("v2", options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API v2";
        doc.Info.Version = "2.0";
        return Task.CompletedTask;
    });
});

Indiquer les versions obsolètes dans la documentation

Si une version est obsolète, faites-le apparaître dans la description de son document afin que les consommateurs voient l’avertissement dans l’interface.

options.AddDocumentTransformer((doc, ctx, ct) =>
{
    if (ctx.DocumentName == "v1")
        doc.Info.Description = "DEPRECATED - migrate to v2.";
    return Task.CompletedTask;
});

Remplacer la version dans les URL

SubstituteApiVersionInUrl = true remplace le jeton de route {version:apiVersion} par la version concrète, par exemple v1, dans le document, afin de rendre les chemins plus lisibles.

// Without: /api/v{version}/products
// With:    /api/v1/products

Un onglet d’interface par version

La plupart des visualiseurs peuvent afficher une liste déroulante contenant tous les documents. Configurez l’interface pour qu’elle pointe vers le fichier JSON de chaque version.

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "API v1", "/openapi/v1.json");
    options.AddDocument("v2", "API v2", "/openapi/v2.json");
});

Documenter les structures des requêtes et des réponses

Comme v2 peut modifier les DTO, donnez à chaque version ses propres types de DTO. OpenAPI génère alors automatiquement des schémas distincts pour chaque document.

// V1 DTO
public record ProductV1(int Id, string Name);
// V2 DTO (breaking change)
public record ProductV2(int Id, string Title, decimal Price);

Assembler le tout

Le déroulement complet : configurer la gestion des versions et l’explorateur d’API, enregistrer un document OpenAPI par version avec un filtre, les publier, puis faire pointer votre interface vers chacun d’eux.

builder.Services.AddApiVersioning().AddApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV";
    o.SubstituteApiVersionInUrl = true;
});
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// ...
app.MapOpenApi();
app.MapScalarApiReference();

Vérification rapide

Vérifiez comment les documents dont les versions sont gérées sont produits.

Récapitulatif

Vous avez documenté des API dont les versions sont gérées :

Enregistrez un document OpenAPI nommé par version avec AddOpenApi("vN").
IApiVersionDescriptionProvider énumère les versions ; ShouldInclude filtre les points de terminaison.
SubstituteApiVersionInUrl affiche des chemins avec la version concrète.
Faites pointer l’interface vers chaque document pour obtenir une vue par version.

Le cours sur la gestion des versions et OpenAPI est maintenant terminé.

Questions Fréquemment Posées

La leçon « Documenter les API versionnées » est-elle gratuite ?

Oui — le texte complet de « Documenter les API versionnées » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours C# Academy, passe à CoddyKit PRO. Le cours C# Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Documenter les API versionnées » ?

Exposez la documentation de plusieurs versions d’API. Tu pratiques C# Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer C# Academy ?

Aucune expérience préalable n'est requise. C# Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Documenter les API versionnées » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon C# Academy ?

Oui. Chaque leçon C# Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à C# Academy