La documentation d’API

Introduction

La documentation des API est un sujet extrêmement important et à ne pas délaisser lors de la construction de services web. Au-delà de l’aspect pur « bonnes pratiques de développement », cette documentation doit permettre à n’importe qui ou n’importe quel service de comprendre l’usage de l’API développée, comment l’exploiter, quelles données seront retournées, quelles actions seront effectuées et - en somme - quel va être le résultat de l’appel.

Fort heureusement, le standard HTTP et les principes REST permettent de bien cadrer les éléments techniques d’une Web API : code de retour, route HTTP, variables nommées, verbe HTTP, en-tête de requête et de réponse… Cependant, ces éléments ne sont pas forcément tout de suite visibles lorsque le développeur souhaite exploiter une API. Par exemple, la route d’une API est directement visualisable puisque le développeur doit l’utiliser pour faire son appel, mais le code de retour n’est pas accessible tant qu’il n’a pas effectué l’appel. La documentation permet de décrire tous ces éléments et ainsi faciliter la vie des consommateurs d’API.

Afin d’écrire aisément cette documentation, le développeur...

L’outil Swagger et le standard Open API

Historiquement, Swagger est le nom donné aux outils et standards utilisés pour la documentation d’API. Aujourd’hui, les outils intitulés Swagger sont décorrélés du standard qui s’intitule désormais Open API. Ce même standard a d’ailleurs été construit et rédigé par les équipes de Swagger. Swagger est un ensemble d’outils open source et commerciaux développés par l’entreprise SmartBear Software, pionnière sur les sujets de qualité logicielle notamment avec les outils SoapUI et QAComplete.

Swagger construit plusieurs outils open source à destination des développeurs et des designers d’API. Le premier outil intéressant est Swagger Codegen. Le principe est simple : à partir d’un fichier Open API, Swagger Codegen est capable de générer un serveur web - exposant l’API décrite - et un client permettant d’appeler le serveur et respectant le contrat d’interface de l’API. Cet outil permet notamment d’accélérer la génération de SDK pour les API que les entreprises développent afin que les équipes puissent se focaliser sur les API et leur adoption. Le code généré peut être avec plusieurs langages et frameworks : .NET, PHP, Python, Java, JavaScript…

Voici un exemple de spécification Open API permettant de générer une API concernant des articles :

openapi: 3.0.0 
info: 
 title: Articles API 
 version: 1.0.0 
servers: 
 - url: http://localhost:8080/api/v1 
paths: 
 /articles: 
   get: 
     description: Récupération la liste des articles 
     responses: 
       200: 
         description: La liste des articles 
         content: 
           application/json: 
             schema: 
               type: array 
               items: 
                 $ref: '#/components/schemas/Article' ...

L’intégration dans les contrôleurs

Swagger s’intègre facilement dans une solution ASP.NET Core notamment en ajoutant des attributs sur les contrôleurs API des projets web. Dans un premier temps, il faut rajouter le paquet NuGet permettant d’utiliser Swagger au sein de notre projet.

dotnet add package Swashbuckle.AspNetCore 

Il faut ensuite configurer le projet dans le Startup.cs et plus précisément dans la méthode ConfigureServices avec le code suivant :

public void ConfigureServices(IServiceCollection services) 
{ 
   services.AddSwaggerGen(c => 
   { 
       c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", 
Version = "v1" }); 
   }); 
   services.AddControllers(); 
} 

La méthode AddSwaggerGen ajoute tous les services nécessaires à la bonne génération de la documentation dans le projet. Il est ensuite possible de rajouter plusieurs documentations (version, jeu d’API …) et l’objet OpenApiInfo permet de spécifier quelques informations propres à chaque documentation. Cela veut dire qu’il est possible - dans un seul projet web - de générer plusieurs documentations d’API selon vos besoins.

Enfin, dans la méthode Configure, il faut rajouter l’accès...

Swagger UI et la documentation interactive

Swagger UI est un outil open source générant une interface utilisateur qui permet de visualiser et d’interagir avec une API REST documentée avec OpenAPI. Swagger UI fournit une interface utilisateur basée sur un navigateur pour explorer les API documentées, exécuter des requêtes et voir les réponses.

La spécification OpenAPI peut être au format JSON ou YAML. L’outil prend en charge les opérations CRUD standards (GET, POST, PUT, DELETE) ainsi que d’autres types d’opérations personnalisées, des en-têtes d’autorisation personnalisés, des paramètres de requête ainsi que les contenus de requête, des options de pagination et bien plus encore.

En utilisant Swagger UI, les développeurs peuvent rapidement comprendre comment utiliser une API et interagir avec elle, sans avoir à écrire de code ou à configurer des outils externes. Cela facilite grandement l’adoption de l’API et améliore l’expérience utilisateur.