L'essentiel sur la documentation OpenAPI
- La documentation de l'API Raisetalk est désormais publiée au format OpenAPI, accessible à l'adresse api.raisetalk.com/docs
- Elle est générée automatiquement à partir du code source de l'API et mise à jour à chaque déploiement : pas de dérive entre la documentation et la réalité des endpoints
- Un SDK client peut être généré en une commande dans la quasi-totalité des langages courants (PHP, Python, TypeScript, Java, Go, Ruby, C#, etc.) via l'outil open source
openapi-generator-cli - Le fichier de spécification brut est également accessible à api.raisetalk.com/openapi.yaml pour alimenter vos propres outils (Postman, Insomnia, tests de contrat, CI/CD)
Une documentation API au format standard du marché
L'API Raisetalk permet, depuis le premier jour, à nos clients et partenaires d'intégrer la plateforme dans leurs propres outils : upload de conversations à analyser, récupération des transcriptions et des analyses, gestion des grilles de Quality Monitoring / Voix du Client, callbacks en temps réel, etc.
Jusqu'ici, la documentation vivait en page statique, exposée au risque classique : la doc qui dérive du code. Un paramètre renommé, un champ ajouté, un endpoint déprécié, et l'écart s'installe.
Nous avons basculé cette documentation vers une spécification OpenAPI, le standard de facto pour décrire une API REST. Et surtout : cette spécification est générée automatiquement à partir du code source de l'API, puis publiée à chaque déploiement. La doc que vous lisez reflète exactement le comportement des endpoints en production.
Ce que ça change pour vos intégrations
Zéro dérive entre la doc et la réalité
Chaque déploiement régénère la spec. Si un champ est ajouté, un paramètre renommé ou un endpoint déprécié, la documentation en tient compte dans la foulée. Plus besoin de vérifier la cohérence à la main, plus de ticket "la doc ne matche pas ce que renvoie l'API".
Un SDK dans le langage de votre choix, en une commande
À partir du fichier openapi.yaml, l'outil open source openapi-generator-cli (maintenu par la communauté OpenAPI Tools) génère un client fonctionnel dans plus de 50 langages cibles : PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust, etc. Exemple pour PHP :
docker run --rm \
-v "${PWD}:/local" \
openapitools/openapi-generator-cli generate \
-i https://api.raisetalk.com/openapi.yaml \
-g php \
-o /local/sdk/php
Pour changer de langage cible, il suffit de remplacer la valeur du paramètre -g. Par exemple :
| Langage | Paramètre -g |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
La liste complète des générateurs disponibles, ainsi que les options de configuration, sont documentées sur le site officiel : openapi-generator.tech.
Une spec exploitable par vos outils existants
Le fichier openapi.yaml peut être importé directement dans la plupart des outils d'API : Postman, Insomnia, Bruno, mais aussi les tests de contrat (Pact, Dredd, Schemathesis), les proxies et gateways (Kong, Tyk), ou encore vos pipelines CI/CD pour détecter automatiquement les ruptures de contrat entre deux versions.
Comment explorer la documentation
Rendez-vous sur api.raisetalk.com/docs : chaque endpoint est présenté avec ses paramètres, ses réponses types, les codes d'erreur possibles et des exemples de payload. L'interface permet également d'essayer les endpoints directement depuis le navigateur, avec votre token Bearer.
La page Documentation API de notre site renvoie désormais directement vers cette spec, ainsi que vers le fichier openapi.yaml si vous souhaitez le récupérer pour vos propres outils.
Pour aller plus loin
- Découvrir la documentation OpenAPI : api.raisetalk.com/docs
- Récupérer le fichier de spec : api.raisetalk.com/openapi.yaml
- Générer un SDK : openapi-generator.tech
- Discuter d'un cas d'intégration : prenez contact avec nous
Publier une spécification OpenAPI auto-générée n'est pas juste un détail d'ingénierie : c'est un engagement sur la fiabilité de la documentation et sur l'ouverture de la plateforme. Pour vos équipes techniques, c'est l'assurance que ce qui est décrit dans la doc est bien ce qui tourne en production, et qu'un SDK fonctionnel est à une commande de distance.
