Das Wichtigste zur OpenAPI-Dokumentation
- Die Dokumentation der Raisetalk-API wird jetzt im OpenAPI-Format veröffentlicht, verfügbar unter api.raisetalk.com/docs
- Sie wird automatisch generiert aus dem Quellcode der API und bei jedem Deployment aktualisiert: kein Auseinanderdriften zwischen Dokumentation und tatsächlichem Verhalten der Endpunkte
- Ein Client-SDK kann in einem einzigen Befehl generiert werden in nahezu allen gängigen Sprachen (PHP, Python, TypeScript, Java, Go, Ruby, C#, usw.) mit dem Open-Source-Tool
openapi-generator-cli - Die rohe Spezifikationsdatei ist ebenfalls unter api.raisetalk.com/openapi.yaml abrufbar, um Ihre eigenen Werkzeuge (Postman, Insomnia, Contract-Tests, CI/CD) damit zu versorgen
Eine API-Dokumentation im Marktstandard
Die Raisetalk-API erlaubt es unseren Kunden und Partnern vom ersten Tag an, die Plattform in ihre eigenen Tools zu integrieren: Upload von Gesprächen zur Analyse, Abruf von Transkripten und Analysen, Verwaltung der Bewertungsraster für Quality Monitoring / Voice of the Customer, Echtzeit-Callbacks usw.
Bisher existierte die Dokumentation als statische Seite, anfällig für das klassische Risiko: Dokumentation, die vom Code abdriftet. Ein umbenannter Parameter, ein hinzugefügtes Feld, ein veralteter Endpunkt, und schon entsteht eine Lücke.
Wir haben diese Dokumentation auf eine OpenAPI-Spezifikation umgestellt — den De-facto-Standard zur Beschreibung einer REST-API. Entscheidend ist: Diese Spezifikation wird automatisch aus dem Quellcode der API generiert und bei jedem Deployment veröffentlicht. Die Dokumentation, die Sie lesen, entspricht exakt dem Verhalten der Endpunkte in der Produktion.
Was sich für Ihre Integrationen ändert
Null Abweichung zwischen Dokumentation und Realität
Jedes Deployment regeneriert die Spec. Wird ein Feld hinzugefügt, ein Parameter umbenannt oder ein Endpunkt als veraltet markiert, wird die Dokumentation unmittelbar angepasst. Keine manuelle Konsistenzprüfung mehr, keine Tickets mehr wie "die Doku stimmt nicht mit dem API-Rückgabewert überein".
Ein SDK in der Sprache Ihrer Wahl, in einem einzigen Befehl
Aus der Datei openapi.yaml erzeugt das Open-Source-Tool openapi-generator-cli (betreut von der OpenAPI-Tools-Community) einen funktionsfähigen Client in mehr als 50 Zielsprachen: PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust usw. Beispiel für 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
Um eine andere Zielsprache zu wählen, genügt es, den Wert des Parameters -g zu ändern. Beispiele:
| Sprache | Parameter -g |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
Die vollständige Liste der verfügbaren Generatoren und Konfigurationsoptionen ist auf der offiziellen Website dokumentiert: openapi-generator.tech.
Eine Spec, die von Ihren bestehenden Tools genutzt werden kann
Die Datei openapi.yaml lässt sich direkt in die gängigsten API-Tools importieren: Postman, Insomnia, Bruno, sowie in Contract-Testing-Tools (Pact, Dredd, Schemathesis), Proxies und Gateways (Kong, Tyk) oder in Ihre CI/CD-Pipelines, um Vertragsbrüche zwischen zwei Versionen automatisch zu erkennen.
Die Dokumentation erkunden
Besuchen Sie api.raisetalk.com/docs: Jeder Endpunkt wird mit seinen Parametern, Beispielantworten, möglichen Fehlercodes und Payload-Beispielen vorgestellt. Die Oberfläche erlaubt es außerdem, die Endpunkte direkt aus dem Browser heraus mit Ihrem Bearer-Token zu testen.
Die Seite API-Dokumentation unserer Website verweist nun direkt auf diese Spec sowie auf die Datei openapi.yaml, falls Sie sie für Ihre eigenen Tools abrufen möchten.
Weiterführende Informationen
- OpenAPI-Dokumentation entdecken: api.raisetalk.com/docs
- Spec-Datei herunterladen: api.raisetalk.com/openapi.yaml
- Ein SDK generieren: openapi-generator.tech
- Einen Integrationsfall besprechen: Kontakt aufnehmen
Eine automatisch generierte OpenAPI-Spezifikation zu veröffentlichen ist kein bloßes Engineering-Detail — es ist ein Bekenntnis zur Verlässlichkeit der Dokumentation und zur Offenheit der Plattform. Für Ihre Technik-Teams bedeutet es: Was in der Dokumentation beschrieben ist, entspricht genau dem, was in der Produktion läuft, und ein funktionsfähiges SDK ist nur einen Befehl entfernt.
