Résolution de problèmes d’importation d’API

Cet article constitue une référence consolidée pour chaque erreur, avertissement et comportement inattendu documenté dans la fonctionnalité de documentation API de Document360. Utilisez-le pour diagnostiquer et résoudre des problèmes liés aux importations, à l’authentification, à la fonctionnalité Essayez-le !, au rendu et au site de la base de connaissances.

Erreurs d’importation

Format invalide – Échec du téléchargement du fichier API

Quand cela se produit : Lorsqu’une ou plusieurs réponses dans votre fichier de spécification OpenAPI manquent, la section requise content .

Pourquoi cela arrive : Document360 applique des règles strictes de validation OpenAPI. Bien qu’un fichier puisse passer la validation dans des outils comme Swagger Editor, Document360 exige que toutes les réponses définissent explicitement à la fois le type de média (par exemple, application/json) et une référence de schéma sous un content bloc. Les réponses vides ou qui font directement référence à un schéma sans content enveloppe provoqueront cette erreur.

Comment le corriger :

1. Ouvrez votre fichier de spécification OpenAPI dans un éditeur de texte ou un IDE.
2. Localisez toutes les définitions de réponse vides ou qui font référence à un schéma sans content bloc.
   Incorrect :

   responses:
     "200": {}

Correct :

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/YourSchema"

3. Sauvegardez le fichier et téléchargez-le à nouveau sur Document360.
   Si le problème persiste, contactez l’équipe d’assistance de Document360 .

URL invalide

Quand cela se produit : Lors de la création d’une référence API à partir d’une URL, l’URL fournie ne peut pas être récupérée ou résolue.

Pourquoi cela arrive : L’URL peut être déformée, inaccessible depuis les serveurs de Document360, ou pointer vers une ressource qui n’est pas une spécification valide d’OpenAPI.

Comment le corriger : Vérifiez que l’URL se résout correctement dans un navigateur ou avec curl. Assurez-vous qu’il renvoie un document OpenAPI valide en JSON ou YAML. Corrigez l’URL et réessayez.

Format de fichier non pris en charge

Quand cela se produit : Lorsque le fichier téléchargé n’est pas un format pris en charge.

Comment le corriger : Assurez-vous que votre fichier est l’un des suivants : JSON, YAML ou YML. Document360 prend en charge OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et Postman Collections.

Impossible d’ajouter une référence API – fichier de spécification invalide

Message d’erreur : « Impossible d’ajouter une référence API. Cette opération ne peut pas être menée à terme. Veuillez vous assurer d’avoir fourni un fichier de spécifications valide. »

Quand cela se produit : Lors du téléchargement d’un fichier de spécification YAML qui a été copié ou exporté depuis un éditeur de texte enrichi ou un traitement de texte.

Pourquoi cela arrive : Le fichier YAML téléchargé est mal formé et n’est pas un document YAML OpenAPI 3.0 valide. Cela se produit fréquemment lorsque le fichier a été copié ou exporté depuis un éditeur de texte enrichi, qui introduit des caractères de mise en forme tels que \f0\fs24 des barres oblique inverses qui cassent le format YAML.

1. Validez votre fichier de spécifications : Ouvrez votre fichier YAML dans un outil comme Swagger Editor ou un éditeur de code pour vérifier les erreurs ou les problèmes de mise en forme.
2. Recherchez les caractères de mise en forme indésirables : vérifiez s’il y a des caractères comme \f0\fs24 ou des barres oblique \ (surtout dans la description du point de terminaison) qui auraient pu être introduits lors d’un copier-coller depuis une source en texte enrichi. Celles-ci peuvent casser le format YAML.
3. Nettoyez le fichier : utilisez un texte brut ou un éditeur de code pour supprimer tout caractère de mise en forme spécial. Évitez d’utiliser des traitements de texte lors de l’édition ou de l’enregistrement de fichiers YAML.
4. Téléversez à nouveau le fichier : Après avoir nettoyé le fichier et vérifié qu’il s’agit d’un YAML OpenAPI 3.0 valide, essayez de le télécharger à nouveau.

Résumé et tags non reflétés après l’importation

Quand cela se produit : Après avoir importé une spécification, les articles de point final affichent des titres incorrects ou apparaissent dans des dossiers de catégories inattendus.

Pourquoi cela arrive : Les summary champs et tags sont définis au niveau du chemin dans la spécification plutôt qu’à l’intérieur de l’objet d’opération (get, post, put, ou delete). De plus, le tags champ doit toujours être écrit comme un tableau, même lorsqu’une seule balise est utilisée.

Comment le corriger :

1. Ouvrez votre fichier de spécification OpenAPI dans un éditeur de texte.
2. Déplacez les summary champs et tags à l’intérieur de chaque objet d’opération et assurez-vous tags que cela soit écrit comme un tableau.
   Incorrect :

   /your-endpoint:
     summary: My Endpoint
     tags: My Category
     get:
       ...

Correct :

   /your-endpoint:
     get:
       summary: My Endpoint
       tags: ["My Category"]
       ...

3. Sauvegardez le fichier et réimportez-le dans Document360. Les articles importés utiliseront la summary valeur comme titre de l’article, et les dossiers basés sur des tags seront créés correctement.
   Si le problème persiste, contactez l’équipe d’assistance de Document360 .

Échec de téléversement avec 400 Mauvaise requête – fichier de spécifications trop volumineux

Quand cela se produit : Lors du téléchargement d’un fichier de spécification OpenAPI YAML ou JSON valide qui contient des points de terminaison avec des schémas de réponse profondément imbriqués et plusieurs codes de réponse par terminaison.

Pourquoi cela arrive : Bien que le fichier puisse être un YAML valide et passer des validateurs externes tels que Swagger Editor, Document360 impose une limite interne de taille d’article. Lorsqu’un point d’extrémité contient des schémas de réponse imbriqués huit niveaux ou plus à travers plusieurs codes de réponse, la taille de données résultante dépasse cette limite et ne peut ni être traitée ni stockée.

Comment le corriger :

1. Ouvrez votre fichier de spécification OpenAPI dans un éditeur de texte ou un IDE.
2. Pour chaque extrémité, ne conservez qu’un seul type de réponse 201, un type de réponse série 400 et le type de réponse par défaut. Supprimez tous les codes de réponse supplémentaires.
3. Pour les points de terminaison où la réponse 201 seule contient des schémas profondément imbriqués, conservez uniquement le type de réponse 201 et supprimez complètement la série 400 et les types de réponse par défaut.
4. Sauvegardez le fichier modifié et téléversez-le à nouveau sur Document360.

i️ NOTE
Si la publication échoue après un téléchargement réussi, contactez l’équipe de support de Document360. La publication peut nécessiter une assistance en arrière-plan en raison de la limitation de la taille de l’article.

Descriptions de balises de premier niveau non affichées dans la documentation de l’API

Quand cela se produit : Les descriptions et métadonnées définies dans les objets de tag OpenAPI de haut niveau ne sont pas affichés dans la documentation générée de l’API.

Pourquoi cela arrive : Lorsqu’un fichier de spécification OpenAPI contient des balises de premier niveau utilisées pour regrouper les opérations API, Document360 convertit ces balises en catégories de type dossier lors de l’importation. Les catégories de dossiers sont utilisées uniquement pour organiser les terminaux et ne génèrent pas de pages de contenu autonomes. En conséquence, toute description ou métadonnées définie dans ces objets de tag de premier niveau n’est pas rendue par le rendu.

Solution de contournement : Ajoutez le contexte pertinent directement aux descriptions individuelles des points d’accès dans l’étiquette, afin que les informations soient visibles sur les pages de points générés.

Vous avez toujours des problèmes ?

Si les étapes ci-dessus ne résolvent pas votre problème, contactez directement l’équipe d’assistance de Document360 .

FAQ