D’un fichier OpenAPI ou Swagger à un logigramme

OpenAPI et Swagger en un paragraphe

La spécification OpenAPI est un format standard, en JSON ou en YAML, pour décrire des API HTTP : chemins, opérations, paramètres et réponses. Elle est née sous le nom de spécification Swagger ; la version 2.0 est encore souvent appelée « Swagger 2 », et la norme s’est poursuivie sous le nom OpenAPI 3.x. Les outils s’en servent pour générer documentation, clients et tests.

Pourquoi la spécification seule ne suffit pas

Une spécification est un catalogue : elle indique que POST /clients, POST /controles-kyc et POST /comptes existent. Elle ne dit pas qu’un client doit passer le contrôle KYC avant l’ouverture du compte, ni ce qui se passe si le contrôle échoue. Cet ordre et ces règles constituent le processus métier, et ils vivent dans la tête des équipes ou dans d’autres documents.

L’approche combinée

1. Décrivez le processus en quelques phrases, en nommant qui ou quoi réalise chaque étape : voir bien décrire un processus à l’IA.
2. Joignez la spécification (OpenAPI 3 ou Swagger 2, en .json, .yaml ou .yml).
3. Générez : les étapes viennent de votre description ; les étapes automatiques réalisées par le système sont associées à l’endpoint le plus pertinent, qui s’affiche sur l’étape, par exemple POST /controles-kyc.
4. Vérifiez les associations : chaque endpoint est-il bien celui qui est appelé ? Corrigez un écart en le demandant, par exemple « utilise PUT /comptes/{id} pour l’activation ».

Ce que Flowchartio lit dans le fichier

Flowchartio détecte les fichiers OpenAPI et Swagger, liste leurs opérations sous la forme « MÉTHODE /chemin » et s’en sert pendant la génération. Les fichiers sont limités à 5 Mo. Les autres fichiers JSON, YAML et XML sont acceptés comme contexte, et les services SOAP s’importent à partir de leur WSDL.

Un exemple court

Description : « Un visiteur s’inscrit. Le système crée le client, puis lance le contrôle KYC. Si le contrôle échoue, le client est prévenu. Sinon, le système ouvre le compte et envoie un e-mail de bienvenue. » Avec une spécification qui contient ces endpoints, le résultat comporte un couloir Système où « Créer le client », « Lancer le contrôle KYC », « Ouvrir le compte » et « Envoyer l’e-mail de bienvenue » portent chacun leur endpoint, plus une décision sur le résultat du contrôle.

Exploiter le résultat

• Partagez-le avec les équipes produit et support, qui ne lisent pas les spécifications.
• Collez l’export Mermaid dans le dépôt, à côté de la spécification ; voir Mermaid sur GitHub et GitLab.
• Complétez-le en documentation d’intégration avec relances et erreurs : documenter un workflow d’intégration d’API.

Importez votre spécification et générez le logigramme.