Mathieu Desnouveaux

An Alternative View on Open API Docs

Start Finally Doing It Right

#API Days Paris 2024
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.

Lors de la conférence "An Alternative View on Open API Docs: Start Finally Doing It Right" des "API Days Paris 2024", Maxim Danilov a discuté des défis liés à la documentation des spécifications OpenAPI (OAS) et a proposé des solutions pour les surmonter. Il a souligné que bien que les spécifications OpenAPI décrivent l'utilisation des API HTTP, elles ne fournissent pas de directives claires sur l'organisation ou la découverte de la documentation. De plus, la documentation est souvent difficile à comprendre pour les humains et les ordinateurs, et les tests de grandes spécifications OAS consomment beaucoup de ressources.

Pour résoudre ces problèmes, Danilov a suggéré de diviser la documentation en fichiers plus petits pour améliorer la lisibilité et réduire la consommation de ressources. Il a également recommandé d'utiliser la méthode option pour fournir de petits fichiers YAML et d'utiliser un service pour servir ces fichiers à partir de spécifications OAS plus grandes. Ces solutions visent à rendre la documentation des API plus accessible et efficace.