Avec le plugin IDEA d'Apidog ou certains plugins Swagger, vous pouvez facilement générer la documentation API à partir du code, résolvant ainsi le problème de la rédaction de la documentation à partir de zéro.
Cependant, même après la rédaction des endpoints et la génération de la documentation, vous pourriez encore vous poser des questions : la conception de l'API est-elle suffisamment bonne ? La documentation est-elle standardisée ? Y a-t-il des aspects qui peuvent être davantage améliorés ?
Surtout dans le cadre d'une collaboration en équipe, vous voulez que votre documentation API soit facile à comprendre pour vos coéquipiers en un coup d'œil. La clarté des noms et l'exhaustivité des informations affectent directement leur expérience d'utilisation de vos API.
Apidog a récemment déployé plusieurs fonctionnalités d'IA pour vous aider à optimiser davantage la documentation API à ce stade. Que vous amélioriez les détails des endpoints existants ou importiez des documents API existants d'ailleurs, l'IA peut offrir des suggestions pratiques.
Ci-dessous, nous allons voir comment utiliser l'IA dans Apidog pour créer une documentation API plus standardisée. Avant de commencer, assurez-vous d'avoir mis à jour Apidog vers la dernière version, activé les fonctionnalités d'IA et configuré le modèle d'IA.
Importer depuis une documentation existante
Parfois, vous devez migrer la documentation API d'autres sources vers Apidog. Si la documentation est dans un format standard, Apidog prend en charge nativement plusieurs méthodes d'importation : vous pouvez générer de la documentation à partir du code via le plugin IDEA, importer des spécifications OpenAPI/Swagger, ou migrer depuis d'autres outils comme Postman.
Mais dans certains cas, votre documentation peut ne pas être dans ces formats standard. Par exemple, l'équipe a pu documenter précédemment des endpoints en Markdown, organiser des descriptions de champs dans Word, ou trouver des définitions d'endpoints dans des journaux de chat ou des e-mails. Saisir manuellement chaque champ de ces sources non standard dans Apidog peut être intimidant.
Dans cette situation, vous pouvez utiliser la fonctionnalité Modifier le schéma avec l'IA pour faciliter la saisie des données. Supposons que vous ayez un contenu Markdown comme ceci :
| nom | description | type | requis |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Activer ou non la pagination | boolean | true |
| offset | Position de départ (requise lorsque la pagination est activée) | int | false |
| pageSize | Nombre d'éléments par page (requis lorsque la pagination est activée) | int | false |
| minPrice | Prix minimum (unité : cents) | int | false |
| maxPrice | Prix maximum (unité : cents) | int | false |
| brand | Code de la marque | string | false |
| categoryId | ID de la catégorie de produit | int | false |
| sortRule | Règle de tri : 1 → Priorité aux ventes, 2 → Prix croissant, 3 → Prix décroissant | enum(int) | false |
| keyword | Mot-clé de recherche (correspondance floue sur le nom du produit) | string | false |Copiez simplement les paramètres et demandez à l'IA : "Convertissez ce contenu en paramètres d'endpoint, en veillant à identifier les types et les champs obligatoires."
L'IA détectera automatiquement les noms de champs, les types de données, le statut obligatoire et les descriptions, puis convertira le tout au format de schéma standard d'Apidog. Si des énumérations sont incluses, l'IA les organisera également en types d'énumérations appropriés pour vous.
L'IA vous aide à affiner les détails de l'API
Après avoir importé les informations de base, l'étape suivante consiste à affiner les détails.
Si vous n'êtes pas sûr d'un nom de champ, utilisez la fonctionnalité AI naming (nommage par IA). L'IA fournira des suggestions de nommage plus précises conformément aux spécifications des endpoints et aux lignes directrices de conception d'API.
Vous pouvez également utiliser l'IA pour compléter automatiquement les descriptions de champs pour des explications plus claires et plus complètes.
La génération de données fictives est une autre force de l'IA. Souvent, nous savons ce qu'un champ représente mais ne sommes pas sûrs des valeurs d'exemple à utiliser. L'IA générera automatiquement des données d'exemple raisonnables basées sur le type et la description du champ.
Vérification de l'exhaustivité de la documentation API : Éviter les omissions
Lorsque la documentation semble presque complète, vous pourriez encore vous demander si des informations clés manquent. À ce stade, utilisez la fonctionnalité Vérification de l'exhaustivité de la documentation API d'Apidog pour voir si quelque chose a été oublié.
L'IA analysera votre documentation API existante sous plusieurs angles pour identifier les informations manquantes ou incomplètes. Elle générera ensuite un rapport détaillé qui attribue un score à chaque élément examiné, vous aidant ainsi à voir rapidement où votre documentation API doit être améliorée.
Le rapport ne vous dit pas seulement quoi faire, il explique aussi pourquoi. Par exemple, vous avez peut-être documenté un format de réponse réussi, mais pas les scénarios d'erreur possibles ; vous avez peut-être des descriptions de champs de base, mais il manque des contraintes d'utilisation ou des exigences de formatage.
Vous pouvez améliorer votre documentation API en suivant les suggestions fournies dans le rapport.
Vérification de la conformité des endpoints : Assurer la cohérence
Au-delà d'être complète, la documentation API doit également être bien standardisée. Au sein d'un même endpoint, le nommage doit suivre un style cohérent, les types de champs doivent être clairement et correctement définis, et les structures de réponse doivent être logiques. Ces détails jouent un rôle clé pour rendre votre documentation facile à lire et à maintenir.
La fonctionnalité vérification de la conformité des endpoints d'Apidog examine votre documentation sous plusieurs angles. Par exemple, si certains champs sont nommés avec des verbes tandis que d'autres utilisent des noms, l'IA signalera l'incohérence et recommandera un style de nommage unifié.
Il vérifie également si les définitions de champs suivent des normes cohérentes, comme éviter les styles de casse mélangés, l'utilisation simultanée de underscores et de camelCase, ou des abréviations incohérentes, puis fournit des suggestions claires sur la façon de résoudre ces problèmes.
Résumé
La création d'une documentation API claire et standardisée est essentielle. Des fonctionnalités comme les cas de test générés par l'IA, dépendent de la qualité de votre documentation : plus elle est complète et cohérente, plus les cas de test générés seront précis et utiles.
Vous n'avez pas besoin d'utiliser toutes les fonctionnalités d'IA en une seule fois ou de refondre votre flux de travail actuel.
C'est un processus graduel. Vous pouvez commencer par importer votre documentation existante, puis appliquer lentement les fonctionnalités d'IA pour l'améliorer et l'affiner. Si vous n'êtes pas sûr d'une suggestion, vous pouvez laisser les choses en l'état et y revenir plus tard lorsque vous aurez plus de contexte.
Avec le temps, vous développerez naturellement une meilleure compréhension des normes de documentation API. L'IA ne se contente pas de résoudre les problèmes immédiats, elle vous aide également à développer de meilleures habitudes de documentation.