Partager via


Création de pages d’aide pour API Web ASP.NET

Ce tutoriel avec du code montre comment créer des pages d’aide pour API Web ASP.NET dans ASP.NET 4.x.

Lorsque vous créez une API web, il est souvent utile de créer une page d’aide, afin que d’autres développeurs sachent comment appeler votre API. Vous pouvez créer toute la documentation manuellement, mais il est préférable de générer automatiquement autant que possible. Pour faciliter cette tâche, API Web ASP.NET fournit une bibliothèque permettant de générer automatiquement des pages d’aide au moment de l’exécution.

Capture d’écran de la page d’aide A SP dot NET A P I, montrant les produits IP disponibles à sélectionner et leurs descriptions.

Création de pages d’aide d’API

Installez ASP.NET et Web Tools mise à jour 2012.2. Cette mise à jour intègre les pages d’aide dans le modèle de projet API web.

Ensuite, créez un projet ASP.NET MVC 4 et sélectionnez le modèle de projet API web. Le modèle de projet crée un exemple de contrôleur d’API nommé ValuesController. Le modèle crée également les pages d’aide de l’API. Tous les fichiers de code de la page d’aide sont placés dans le dossier Zones du projet.

Capture d’écran des options de menu du modèle de projet API web, circonstant les dossiers de la zone et de la page d’aide.

Lorsque vous exécutez l’application, la page d’accueil contient un lien vers la page d’aide de l’API. À partir de la page d’accueil, le chemin relatif est /Help.

Capture d’écran de la page d’accueil, pointant vers les lettres cliquables IP qui ouvrent le lien vers la page d’aide.

Ce lien vous permet d’accéder à une page récapitulative de l’API.

Capture d’écran de la page d’aide récapitulative de l’IPA, montrant les différentes valeurs d’IPA et leur description.

La vue MVC pour cette page est définie dans Areas/HelpPage/Views/Help/Index.cshtml. Vous pouvez modifier cette page pour modifier la mise en page, l’introduction, le titre, les styles, etc.

La partie main de la page est une table d’API, regroupées par contrôleur. Les entrées de table sont générées dynamiquement à l’aide de l’interface IApiExplorer . (J’en parlerai plus tard.) Si vous ajoutez un nouveau contrôleur d’API, la table est automatiquement mise à jour au moment de l’exécution.

La colonne « API » répertorie la méthode HTTP et l’URI relatif. La colonne « Description » contient la documentation pour chaque API. Au départ, la documentation n’est que du texte d’espace réservé. Dans la section suivante, je vais vous montrer comment ajouter de la documentation à partir de commentaires XML.

Chaque API dispose d’un lien vers une page contenant des informations plus détaillées, notamment des exemples de corps de requête et de réponse.

Capture d’écran de l’une des valeurs de sélection d’IPA, montrant les informations de réponse et les formats de corps de réponse.

Ajout de pages d’aide à un projet existant

Vous pouvez ajouter des pages d’aide à un projet d’API web existant à l’aide du Gestionnaire de package NuGet. Cette option est utile pour commencer à partir d’un modèle de projet différent du modèle « API web ».

Dans le menu Outils , sélectionnez Gestionnaire de package NuGet, puis Console du Gestionnaire de package. Dans la fenêtre Console du Gestionnaire de package, tapez l’une des commandes suivantes :

Pour une application C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Pour une application Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Il existe deux packages, l’un pour C# et l’autre pour Visual Basic. Veillez à utiliser celui qui correspond à votre projet.

Cette commande installe les assemblys nécessaires et ajoute les vues MVC pour les pages d’aide (situées dans le dossier Zones/HelpPage). Vous devez ajouter manuellement un lien à la page d’aide. L’URI est /Help. Pour créer un lien dans une vue razor, ajoutez les éléments suivants :

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

Veillez également à inscrire les zones. Dans le fichier Global.asax, ajoutez le code suivant à la méthode Application_Start , si elle n’existe pas déjà :

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

Ajout de la documentation de l’API

Par défaut, les pages d’aide ont des chaînes d’espace réservé pour la documentation. Vous pouvez utiliser des commentaires de documentation XML pour créer la documentation. Pour activer cette fonctionnalité, ouvrez le fichier Areas/HelpPage/App_Start/HelpPageConfig.cs et supprimez les marques de commentaire de la ligne suivante :

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Activez maintenant la documentation XML. Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis sélectionnez Propriétés. Sélectionnez la page Générer .

Capture d’écran du menu déroulant du projet dans la fenêtre de l’Explorateur de solutions, mettant en évidence l’option de génération.

Sous Sortie, case activée fichier de documentation XML. Dans la zone d’édition, tapez « App_Data/XmlDocument.xml ».

Capture d’écran de la boîte de dialogue Sortie, montrant le chemin de sortie et l’option permettant de sélectionner le fichier de documentation XML.

Ensuite, ouvrez le code du ValuesController contrôleur d’API, qui est défini dans /Controllers/ValuesController.cs. Ajoutez des commentaires de documentation aux méthodes du contrôleur. Par exemple :

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

Notes

Conseil : Si vous placez le signe d’insertion sur la ligne au-dessus de la méthode et que vous tapez trois barres obliques, Visual Studio insère automatiquement les éléments XML. Vous pouvez ensuite remplir les espaces.

À présent, générez et réexécutez l’application, puis accédez aux pages d’aide. Les chaînes de documentation doivent apparaître dans la table d’API.

Capture d’écran du tableau API dans les pages d’aide, montrant la chaîne de documentation dans la valeur et la description de l’API.

La page d’aide lit les chaînes du fichier XML au moment de l’exécution. (Lorsque vous déployez l’application, veillez à déployer le fichier XML.)

En coulisses

Les pages d’aide sont basées sur la classe ApiExplorer , qui fait partie de l’infrastructure d’API web. La classe ApiExplorer fournit la matière première pour créer une page d’aide. Pour chaque API, ApiExplorer contient une apiDescription qui décrit l’API. À cet effet, une « API » est définie comme la combinaison de la méthode HTTP et de l’URI relatif. Par exemple, voici quelques API distinctes :

  • GET /api/Products
  • GET /api/Products/{id}
  • POST /api/Products

Si une action de contrôleur prend en charge plusieurs méthodes HTTP, ApiExplorer traite chaque méthode comme une API distincte.

Pour masquer une API de l’ApiExplorer, ajoutez l’attribut ApiExplorerSettings à l’action et définissez IgnoreApi sur true.

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

Vous pouvez également ajouter cet attribut au contrôleur pour exclure le contrôleur entier.

La classe ApiExplorer obtient les chaînes de documentation de l’interface IDocumentationProvider . Comme vous l’avez vu précédemment, la bibliothèque pages d’aide fournit un IDocumentationProvider qui obtient la documentation à partir de chaînes de documentation XML. Le code se trouve dans /Areas/HelpPage/XmlDocumentationProvider.cs. Vous pouvez obtenir la documentation d’une autre source en écrivant votre propre IDocumentationProvider. Pour le relier, appelez la méthode d’extension SetDocumentationProvider , définie dans HelpPageConfigurationExtensions

ApiExplorer appelle automatiquement l’interface IDocumentationProvider pour obtenir des chaînes de documentation pour chaque API. Il les stocke dans la propriété Documentation des objets ApiDescription et ApiParameterDescription .

Étapes suivantes

Vous n’êtes pas limité aux pages d’aide affichées ici. En fait, ApiExplorer ne se limite pas à la création de pages d’aide. Yao Huang Lin a écrit d’excellents billets de blog pour vous faire penser prête à l’emploi: