Vous vous demandez peut-être ce qu'est la documentation des API et pourquoi nous en avons besoin.
API documentation
Application Programming Interface, en français interface de programmation d'applications (API) est un logiciel intermédiaire qui permet à deux applications de communiquer entre elles. L'application peut faire référence à un logiciel, tandis que le mot interface peut être considéré comme un contrat ou un service entre deux applications.
En termes non techniques, une API est le messager qui transmet votre question à votre ami et qui revient avec la réponse.
Créons une hypothèse : Vos amis sont des ordinateurs et votre connaissance d'eux est une documentation API.
Vous avez deux amis. Bert est un professeur de mathématiques. Votre autre ami s'appelle Tim. Tim a de la famille en Allemagne avec qui il parle allemand.
Vous êtes au travail et vous créez un e-mail pour votre client qui parle allemand. Il vous faut beaucoup de temps pour écrire cet e-mail et vous aimeriez que quelqu'un l'examine et le corrige si nécessaire. Cet e-mail doit être envoyé le plus rapidement possible.
Sans cette documentation API :
Vous pouvez demander ou non une réponse à vos deux amis et la prise en charge risque de prendre plus longtemps.
Vous pourriez envoyer cet e-mail avec des erreurs encore présentes.
Avec la documentation de l'API :
Vous pouvez voir que Bert ne peut pas répondre à votre question (ou demande) alors que Tim peut. Vous savez maintenant à QUI vous adresser et COMMENT le demander. Votre courrier a été corrigé et envoyé sans aucun problème ni stress.
Comme nous pouvons le constater, la documentation des API peut vous faire gagner beaucoup de temps.
Swagger est une technologie qui vous permet de décrire et de lire la structure de vos API. Grâce à cela, nous pouvons créer une documentation interactive pour chaque API. Swagger peut générer un stub serveur, des bibliothèques client et une documentation API interactive. Dans cet article, nous allons approfondir l'interface Swagger qui est responsable de la documentation des API.
La documentation générée ressemble un peu à ceci :
La présentation générale de ces paquets est facile à suivre et ne prend pas trop de temps. Ce sont les annotations qui vous prennent le plus de temps si vous voulez la documentation complète (paramètres, réponses, etc.).
À l'heure actuelle, il est mieux intégré à Microsoft.
Manuellement
En écrivant manuellement des annotations pour vos points de terminaison, vous générez les informations nécessaires à Swagger. Avec celles-ci, Swagger peut générer un fichier JSON ou YAML qui peut être utilisé pour générer une page frontend interactive qui affichera votre documentation API.
En tant que programmeurs, le travail manuel n'est pas ce que nous préférons. Bien que de nombreux frameworks interagissent avec swagger d'une manière propre, il faut toujours des annotations dans chaque cadre.
Cette annotation diffère selon les frameworks. Dans Laravel, cela ressemble à :
Il y a des développeurs qui ont travaillé sur des paquets qui utilisent Swagger UI d'une manière qui ne nécessite pas d'annotation. Ces paquets créent la documentation de vos points de terminaison sans annotation. Pour les paramètres, les réponses et la documentation plus détaillée, vous devrez cependant annoter.
Dans .NET : Swashbuckle et NSwag.
Microsoft lui-même recommande ceux-ci.
Laravel : DarkaOnLine
IBM : Swagger UI (plus d'informations à ce sujet ci-dessous).
Node : swagger-node
Faisons un zoom sur le code généré automatiquement pour Laravel.
Que fait ce paquet ? Ce paquet commence par votre routage. Il utilisera votre fichier API pour passer en revue chaque route et examiner attentivement la méthode liée du contrôleur lié.
Cela aura un impact lors de la création de routes avec resource() ou AppSource() commando dans lesquelles chaque route n'a pas une méthode ou un contrôleur derrière elle. Cela vous obligera à ne créer que des routes URL pour les points de terminaison existants. Ce que je trouve, personnellement, un avantage plutôt qu'un inconvénient.
Après avoir utilisé la route, il se rendra dans votre méthode et cherchera des annotations pour les paramètres. Après avoir fait cela pour chaque route, il générera votre fichier JSON avec la documentation.
IBM ne dispose pas d'un paquet automatique et aura besoin d'annotations. En plus de cela, il est soumis à certaines restrictions venant d'IBM lui-même. Restrictions, que vous pouvez facilement trouver dans le lien suivant : https://www.ibm.com/docs/en/app-connect/11.0.0?topic=apis-restrictions-swagger-documents
La documentation de l'API est toujours précieuse, car les autres membres de l'équipe peuvent facilement vérifier les points de terminaison dans la documentation de l'API pour faciliter la collaboration. (Tant que vous continuez à écrire des annotations lorsque vous créez de nouveaux points de terminaison).
Même s'il n'est pas généré automatiquement pour IBM, je pense qu'utiliser cette technologie ou une autre pour documenter votre API vaut vraiment la peine !