Introduction

Si vous avez déjà codé un service WCF alors vous avez eu à exposer un document WSDL (Web Services Description Language) qui vous permet de décrire votre service à travers des métadonnées en langage XML. Ce document permet aux développeurs voulant accéder à votre service de prendre connaissance des différentes opérations exposées, des types en entrée comme en sortie ainsi que les protocoles de communication possible. La technologie ASP.NET Web API est de plus en plus utilisée pour créer les services web sur la plateforme .NET mais le document WSDL n’est pas envisageable pour cette technologie.

Pour qu’un service, surtout s’il est public, soit adopté facilement, il est indispensable qu’une documentation soit disponible pour faciliter son utilisation par les développeurs voulant communiquer avec. Certains outils nous permettent de générer de façon dynamique cette documentation. Dans cette article nous parlerons de deux solutions qui nous facilitent la tâche dans le cas où notre service est développé avec la technologie ASP.NET Web API : ASP.NET Web API Help Page et Swagger. La première solution est fournie par Microsoft tandis que la deuxième définit des spécifications et est en passe de devenir un standard dans la description d’un service REST.

Documentation avec les commentaires XML

Avant de montrer comment générer de la documentation dynamique pour son service à travers les deux solutions citées dans l’introduction, il faut savoir que le descriptif des différentes opérations exposées n’est pas généré par magie. Notre service ASP.NET Web API propose différentes routes permettant d’exécuter des opérations et ces dernières sont définies au niveau des contrôleurs qui à leur tour définissent des actions représentées par des méthodes. Pour que la documentation générée puisse afficher la description des différentes routes il faut impérativement que chacune des actions dispose de commentaires XML comme dans le code ci-dessous :

/// <summary>
/// Mon super contrôleur
/// </summary>
public class ValuesController : ApiController
{
	/// <summary>
	/// Recupére toutes les valeurs
	/// </summary>
	/// <returns>Une collection de valeurs</returns>
	public IEnumerable<string> Get()
	{
		return new string[] { "value1", "value2" };
	}
	/// <summary>
	/// Recupére une valeur via son identifiant
	/// </summary>
	/// <param name="id">L'identifiant de la valeur</param>
	/// <returns>La valeur</returns>
	public string Get(int id)
	{
		return "value";
	}
	/// <summary>
	/// Crée une nouvelle valeur
	/// </summary>
	/// <param name="value">La valeur</param>
	public void Post([FromBody]string value)
	{
	}
	/// <summary>
	/// Modifie une valeur
	/// </summary>
	/// <param name="id">L'identifiant de la valeur</param>
	/// <param name="value">La valeur</param>
	public void Put(int id, [FromBody]string value)
	{
	}
	/// <summary>
	/// Supprime une valeur
	/// </summary>
	/// <param name="id">L'identifiant de la valeur</param>
	public void Delete(int id)
	{
	}
}

Après avoir défini les commentaires XML, il faut activer la génération du fichier XML dans la section Sortie de l’onglet Compilation de la fenêtre Propriétés du projet Visual Studio contenant le code de notre service :

ASP.NET Web API Help Page

À la création d’un nouveau projet ASP.NET et en optant pour le modèle Web API, Visual Studio installera le package NuGet (que vous pouvez installer séparément dans un projet existant) suivant : ASP.NET Web API Help Page. Dans le dossier “Areas” nous avons un sous-dossier “Help” qui contient toute la logique nécessaire à la découverte dynamique des contrôleurs et actions que nous aurons à définir et bien sûr les différentes vues nécessaires à l’affichage de la documentation de notre Web API. Reste à faire quelques petites modifications pour finaliser la configuration. Dans la méthode “Register” de la classe “HelpPageConfig” (dans le fichier “Areas/HelpPage/App_Start/HelpPageConfig. cs”), nous devons dé-commenter la ligne permettant de lire la documentation XML que nous avons configurée dans la section précédente :

config.SetDocumentationProvider(
  new XmlDocumentationProvider(
    string.Format(
      @"{0}\bin\WebApiHelpPage.XML", 
      AppDomain.CurrentDomain.BaseDirectory
    )
  )
);

L’accès à la documentation se fait via l’URL relative “/Help”. La page d’accueil de la documentation se présente comme dans l’image ci-dessous :

La page affichera autant de section qu’il y a de contrôleurs définis dans notre Web API. Chaque section contient un tableau listant les différentes routes précédées de la commande REST à utiliser. Chacune des routes est un lien menant vers une page détaillant beaucoup plus l’action associée à la route en question. Ci-dessous la page descriptive de l’action de modification d’une nouvelle valeur dans notre Web API :

Chaque action est décrite avec :

• un tableau listant les différents paramètres de l’URI . Le tableau spécifie le descriptif du paramètre, le type attendu et s’il est obligatoire ou pas.
• une section Body Parameters affichant les données attendues dans le corps de la requête.
• une section Request Formats montrant des exemples de données pouvant être passées dans le corps de la requête selon le type de négociation de contenu choisi.

Nous avons juste fait le minimum requis dans la configuration pour avoir la documentation de notre service mais pas mal de personnalisations peuvent être effectuées. Pour voir les différentes personnalisations possible il suffit d’ouvrir le fichier “HelpPageConfig. cs” et de lire les différents commentaires dans la méthode “Register” de la classe “HepPageConfig”.

Swagger

Swagger définit des spécifications pour décrire un service et cela indépendamment du langage de programmation utilisé pour implémenter ce service. Il est né de l’initiative de la société Wordnik. Swagger, à travers ses spécifications, tente de définir un standard dans le monde des services web où les standards WSDL et WADL sont déjà largement utilisés selon que vous utilisez respectivement la plateforme .NET ou Java. Swagger en est à sa version 2.0 et ses spécifications sont définies ici.

Pas mal d’outils/librairies pour les différentes technologies et langages de programmation ont été créés par la communauté de développeurs autour de Swagger. Ces outils/librairies nous facilitent la tâche en nous permettant de générer dynamiquement la définition Swagger ainsi que la documentation HTML de notre service REST.

Parmi ces outils, nous avons Swashbuckle pour la plateforme .Net. Une fois ce package Nuget installé, un fichier “SwaggerConfig. cs” est créé dans le dossier “Config”. Ce fichier contient tout le nécessaire à la configuration. Comme pour le package ASP.NET Web API Help Page, nous devons faire quelques petites modifications pour finaliser le paramétrage. La modification à faire dans le fichier “SwaggerConfig. cs” est de dé-commenter la ligne permettant de lire la documentation XML générée dans la première section de cet article :

c.IncludeXmlComments(String.Format(@"{0}\bin\WebApiHelpPage.XML", AppDomain.CurrentDomain.BaseDirectory));

Cependant si vous êtes tenté par quelques personnalisations alors vous pouvez lire les différents commentaires dans ce fichier qui expliquent quelles sont les modifications à faire pour avoir le résultat recherché.

Pour accéder à la documentation en ligne de notre service REST, il suffit d’utiliser l’URL relative : /swagger/ui/index

À peu près comme pour la précédente solution, autant de sections seront affichées qu’il y a de contrôleurs définis dans notre service. Chaque section listera les différentes routes possibles. Chaque route est précédée de la commande REST à utiliser et est suivie d’une description. On peut cliquer sur une route pour déplier une zone qui affichera quelques détails comme comment fournir les paramètres, le type attendu et si le paramètre est requis ou pas. L’image ci-dessous montre les détails pour la route “PUT /api/Values{id}” :

À la différence du package ASP.NET Web API Help Page, Swashbuckle génère pour chaque route un formulaire de tests si des paramètres doivent être fournis ou un simple bouton “Try it out” dans le cas contraire. ASP.NET Web API Help Page ne le permet pas mais un autre package développé par un employé de chez Microsoft permet d’ajouter cette fonctionnalité et ce package NuGet s’appelle WebAPiTestClient.

Comme dit plus haut Swagger se base sur des spécifications pour décrire notre service REST. Cela impose la présence d’un ensemble de fichiers JSON contenant la description du service. Ce sont ces fichiers JSON qui sont générés et utilisés par Swashbuckle pour nous générer respectivement la définition Swagger et l’UI HTML. Avec Swashbuckle le contenu JSON est accessible via l’url relative “/swagger/docs/v1”. Les métadonnées Swagger du service REST utilisé comme exemple dans l’article ressemblent à cela :

Conclusion

Dans cet article nous avons montré l’utilisation de 2 solutions permettant d’avoir une documentation pour son service Web API. ASP.NET Web API Help Page ne va plus loin que la génération de pages HTML tandis que la solution avec Swagger est un peu plus fournie. Comme expliqué, Swagger tente de devenir un standard en mettant en place des spécifications indépendamment de la technologie ce qui n’est pas le cas avec les spécifications WSDL et WADL. Swagger est la solution que je recommande pour décrire son service REST ASP.NET Web API. Il faut noter aussi que les API Apps récemment introduites par Microsoft dans la plateforme Azure utilisent Swagger. Si vous connaissez d’autres solutions facilitant la documentation d’un service REST alors n’hésitez pas à nous en parler en commentaire de cet article.

Avec WCF, il est commun de voir des développeurs générer un proxy côté client généré à partir du document WSDL. Ce proxy représente une classe permettant de faciliter le codage de la communication entre l’application Client et le service WCF. Avec Swagger nous pourrons aussi générer notre proxy à partir de la définition contenue dans le document JSON. Avec .NET l’outil qui nous aidera dans cette tâche s’appelle AutoRest et son utilisation fera l’objet d’un prochain article.