Documentation - mise à jour des spécifications des API

mborne commented 2 weeks ago

Contexte

Les LLM tels ChatGPT sont désormais capables de générer du code et d'appeler des API en s'appuyant sur les spécifications OpenAPI des API en ligne. Les spécifications APICARTO actuelles rédigées pour la mise en oeuvre d'une documentation interactive avec Swagger posent problème pour une exploitation avec ChatGPT.

Proposition

Pour chaque module :

Convertir les spécifications swagger: 2.0 en spécification openapi: 3.1.0

Version à valider avec NORMA IGN ou en inspectant les spécifications des nouvelles OGC API.

Ne plus s'appuyer sur des schémas externes (par exemple pour les schémas GeoJSON décrivant Geometry, Point,...)

La résolution était possible avec swagger: 2.0. Elle n'est pas disponible en openapi: 3.0 et n'est pas supportée par certains outils tels ChatGPT.

Définir un operationId pour chaque endpoint

Certains outils tels ChatGPT s'en servent pour identifier des actions

Remarques

Tester la génération de code et l'intégration sous forme d'actions avec des LLM tels ChatGPT sur la base des spécifications semble être une approche intéressante pour améliorer et valider les spécifications OpenAPI.
Il n'est pas garanti que ces améliorations soient suffisantes pour répondre à des cas d'utilisation avancés impliquant plusieurs appels d'API

Doute sur la capacité de ChatGPT à chaîner des appels pour répondre à des questions du type "Quelles est la superficie de la parcelle située à l'adresse suivante : ..." => (GéoCodage d'adresse -(lon,lat)-> Récupération de la parcelle -> extraction de la superficie

Idée de "services chaînés" à envisager le cas échéant?

mborne commented 2 weeks ago

ping @RubenGres : tu peux me confirmer que j'ai bien compris les échanges?

RubenGres commented 2 weeks ago

Parfaitement résumé!

IGNF / apicarto