Le plugin Coze ne permet pas d’importer OpenAPI 3.1, et ce problème n’est pas rare, surtout si vous collez simplement les définitions d’interface prêtes à l’emploi. Beaucoup pensent qu’ils ne font qu’un ou deux champs, mais en réalité, l’analyse des plugins de Coze est plus sensible à la structure des schémas, et le point le plus probable de rester bloqué est le type de corps de la réponse.
Le rapport d’erreurs courant dans la communauté est très cohérent : non pas « l’interface n’est pas utilisable », mais « la documentation de l’interface n’est pas la forme que Coze attend ». Par exemple, certaines méthodes d’écriture 3.1, schémas de réponse vides et types de joints trop complexes seront bloqués directement lors du processus d’importation.
Pourquoi OpenAPI 3.1 est plus sujet aux problèmes
Comme la 3.1 est plus expressive, l’importateur de plugins peut ne pas considérer toutes les écritures avancées comme des entrées utilisables. Pour les utilisateurs, la documentation s’intéresse aux spécifications ; Pour les importateurs, il peut ne reconnaître que certaines des structures les plus simples. Dans le problème public, quelqu’un s’est retrouvé bloqué dans un endroit du genre « Response Body ne prend en charge que les types d’objets », ce qui indique que les importations de plugins ne sont pas laxistes dans leurs exigences concernant la structure des retours.
Si vous voulez moins marcher sur la fosse, faites ces trois choses d’abord
- Convergez d’abord OpenAPI vers un style 3.0.x plus simple.
- Garde le corps du répondant aussi standard que possible, « objet », et n’écris pas de schémas complexes imbriqués ou vides tout de suite.
- Simplifiez les champs requis, demandez le corps, puis retournez le corps à la version minimale exécutable, puis ajoutez-la progressivement.
Une façon plus pratique de gérer cela dans la communauté
Beaucoup de gens ne « corrigent pas Coze », mais reviennent organiser leurs fichiers OpenAPI et les modifient pour être plus conservateurs. La raison est réaliste : l’objectif des importations de plugins Coze n’est pas de consommer toute la syntaxe OpenAPI, mais de transformer de manière stable les interfaces en plugins appelables. Plus le document est emballé, plus il a de chances d’échouer à l’importation.
Si vous bloquez lors de l’importation, il est recommandé de vérifier si l’erreur pointe vers la structure, le type ou le nom du champ, plutôt que de d’abord soupçonner que l’interface elle-même est inutilisable. Souvent, c’est juste que le schéma est trop sophistiqué et l’importateur ne veut pas deviner.
Conclusion d’une phrase
L’échec du plugin Coze à importer OpenAPI 3.1 n’est principalement pas dû à une mauvaise interface écrite, mais plutôt au fait que la structure du document est trop complexe et que le type de corps de retour n’est pas à la hauteur. En simplifiant d’abord le schéma, le taux de réussite est généralement nettement plus élevé.
