Mathieu Desnouveaux

An Alternative View on Open API Docs: Start Finally Doing It Right

Conférence de Maxim Danilov sur les limites des spécifications OpenAPI actuelles et solutions pour une documentation plus efficace : divide & conquer

La sketchnote de la conférence de Maxim Danilov présente une perspective alternative sur la documentation des spécifications OpenAPI (OAS). En haut à gauche, le titre "API Days Paris 2024" est affiché en lettres blanches sur fond rouge. Le titre de la conférence, "An Alternative View on Open API Docs: Start Finally Doing It Right", est écrit en lettres orange et noires sur fond blanc. La sketchnote est structurée autour de plusieurs blocs et annotations : 1. Un bloc "Problèmes" avec les point suivant : - Les spécifications OpenAPI ne décrivent pas comment organiser ou découvrir la documentation. - La documentation est difficile à comprendre pour les humains et les ordinateurs. - Les tests de grandes spécifications OAS consomment beaucoup de ressources. - Plusieurs standards similaires existent en même temps. 2. Un bloc "Solutions Proposées" avec les points suivant : - Diviser et conquérir : Diviser la documentation en fichiers plus petits pour une meilleure lisibilité et une consommation réduite de ressources. - Utiliser la méthode option : Fournir de petits fichiers YAML. - Utiliser un service : Servir des fichiers YAML à partir de fichiers OAS plus grands. Des flèches relient ces concepts pour montrer les relations entre les problèmes et les solutions proposées.

Cette sketchnote présente An Alternative View on Open API Docs: Start Finally Doing It Right par Maxim Danilov lors des API Days Paris 2024, abordant les limitations des spécifications OpenAPI actuelles et proposant des solutions pratiques.

Contenu de la présentation

Problèmes identifiés : Les spécifications OpenAPI décrivent bien l'usage des APIs HTTP mais manquent de directives pour organiser et découvrir la documentation. La documentation devient difficile à comprendre pour humains et machines, les tests de grandes spécifications consomment beaucoup de ressources, et plusieurs standards similaires coexistent.

Solutions "Divide & Conquer" : Maxim propose de diviser les spécifications monolithiques en fichiers plus petits pour améliorer lisibilité et performance. Cette approche inclut l'utilisation de la méthode OPTIONS pour des fichiers YAML légers et le déploiement de services dédiés pour orchestrer les spécifications fragmentées.

Points clés à retenir

  • Problème d'échelle : Spécifications OpenAPI monolithiques difficiles à gérer
  • Solution modulaire : Divide & conquer avec fichiers YAML plus digestibles
  • Approche service : Services dédiés pour orchestrer la documentation fragmentée
  • Impact performance : Réduction significative de la consommation de ressources
Thèmes:
🔗 API 🛠️ Tools
Événement:
🎤 API Days Paris
Source: Maxim Danilov