Dat Wesentlecht iwwer d'OpenAPI-Dokumentatioun
- D'Dokumentatioun vun der Raisetalk-API gëtt elo am OpenAPI-Format verëffentlecht, ze fannen ënner api.raisetalk.com/docs
- Si gëtt automatesch generéiert, aus dem Quellcode vun der API, a bei all Deployment aktualiséiert: keng Ofwäichung tëscht der Dokumentatioun an der Realitéit vun den Endpoints
- E Client-SDK léisst sech mat engem eenzege Befehl generéieren, a bal alle gängege Programméiersproochen (PHP, Python, TypeScript, Java, Go, Ruby, C# asw.), iwwer dat Open-Source-Tool
openapi-generator-cli - De raue Spezifikatiounsfichier ass och ënner api.raisetalk.com/openapi.yaml disponibel, fir Är eegen Tools domat ze fidderen (Postman, Insomnia, Kontrakttester, CI/CD)
Eng API-Dokumentatioun am Standardformat vum Maart
Zënter dem éischten Dag erlaabt d'Raisetalk-API eise Clienten a Partner, d'Plattform an hir eegen Tools z'integréieren: Upload vu Gespréicher, déi analyséiert solle ginn, Ofruff vun den Transkriptiounen an Analysen, Gestioun vun de Bewäertungsrastere fir Quality Monitoring / Stëmm vum Client, Callbacks an Echtzäit asw.
Bis elo louch d'Dokumentatioun op enger statescher Säit a war dem klassesche Risiko ausgesat: D'Doku dreift vum Code ewech. E Parameter, deen ëmbenannt gëtt, e Feld, dat derbäikënnt, en Endpoint, deen als obsolet markéiert gëtt, an d'Ofwäichung setzt sech fest.
Mir hunn dës Dokumentatioun op eng OpenAPI-Spezifikatioun ëmgestallt, den De-facto-Standard, fir eng REST-API ze beschreiwen. A virun allem: Dës Spezifikatioun gëtt automatesch generéiert, aus dem Quellcode vun der API, an duerno bei all Deployment verëffentlecht. D'Doku, déi Dir liest, spigelt exakt d'Verhale vun den Endpoints a Produktioun erëm.
Wat dat fir Är Integratiounen ännert
Null Ofwäichung tëscht Doku a Realitéit
All Deployment generéiert d'Spec nei. Wann e Feld derbäikënnt, e Parameter ëmbenannt oder en Endpoint als obsolet markéiert gëtt, hëlt d'Dokumentatioun dat direkt op. Dir musst d'Kohärenz net méi mat der Hand iwwerpréiwen, an et gëtt keen Ticket méi vum Typ „d'Doku passt net zu deem, wat d'API zréckschéckt“.
En SDK an der Sprooch vun Ärer Wiel, mat engem eenzege Befehl
Aus dem Fichier openapi.yaml generéiert dat Open-Source-Tool openapi-generator-cli (dat vun der Communautéit OpenAPI Tools gefleegt gëtt) e funktionéierende Client a méi wéi 50 Zilsproochen: PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust asw. E Beispill fir 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
Fir d'Zilsprooch ze wiesselen, geet et duer, de Wäert vum Parameter -g z'ersetzen. Zum Beispill:
| Sprooch | Parameter -g |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
Déi komplett Lëscht vun den disponibele Generatoren, souwéi d'Konfiguratiounsoptiounen, sinn op der offizieller Websäit dokumentéiert: openapi-generator.tech.
Eng Spec, déi Är bestoend Tools notze kënnen
De Fichier openapi.yaml kann direkt an déi meescht API-Tools importéiert ginn: Postman, Insomnia, Bruno, mä och an d'Kontrakttester (Pact, Dredd, Schemathesis), d'Proxyen a Gateways (Kong, Tyk) oder an Är CI/CD-Pipelines, fir automatesch Kontraktbréch tëscht zwou Versiounen z'erkennen.
Wéi Dir d'Dokumentatioun entdecke kënnt
Gitt op api.raisetalk.com/docs: All Endpoint gëtt mat senge Parameteren, sengen typeschen Äntwerten, de méigleche Feelercoden a Beispiller fir Payloads presentéiert. Iwwer d'Interface kënnt Dir d'Endpoints och direkt aus dem Browser probéieren, mat Ärem Bearer-Token.
D'Säit API-Dokumentatioun op eiser Websäit verweist elo direkt op dës Spec, an och op de Fichier openapi.yaml, wann Dir en erofluede wëllt fir Är eegen Tools.
Fir méi wäit ze goen
- D'OpenAPI-Dokumentatioun entdecken: api.raisetalk.com/docs
- De Spec-Fichier eroflueden: api.raisetalk.com/openapi.yaml
- En SDK generéieren: openapi-generator.tech
- En Integratiounsfall beschwätzen: kontaktéiert eis
Eng automatesch generéiert OpenAPI-Spezifikatioun ze verëffentlechen ass net just en Detail vun der Ingenieursaarbecht: Et ass en Engagement fir d'Zouverlässegkeet vun der Dokumentatioun a fir d'Oppenheet vun der Plattform. Fir Är technesch Equippen ass et d'Garantie, datt dat, wat an der Doku beschriwwen ass, och wierklech dat ass, wat a Produktioun leeft, an datt een eenzege Befehl duergeet, fir en SDK ze kréien, dat funktionéiert.
