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.
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.
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.
Ce lien vous permet d’accéder à une page récapitulative de l’API.
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.
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 .
Sous Sortie, case activée fichier de documentation XML. Dans la zone d’édition, tapez « App_Data/XmlDocument.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.
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: