Het belangrijkste over de OpenAPI-documentatie
- De documentatie van de Raisetalk-API wordt nu gepubliceerd in OpenAPI-formaat, bereikbaar op api.raisetalk.com/docs
- Ze wordt automatisch gegenereerd uit de broncode van de API en bij elke deployment bijgewerkt: geen afwijking tussen de documentatie en de werkelijke endpoints
- Een client-SDK genereert u met één commando in vrijwel alle gangbare programmeertalen (PHP, Python, TypeScript, Java, Go, Ruby, C# enz.) met de opensourcetool
openapi-generator-cli - Het ruwe specificatiebestand is ook beschikbaar op api.raisetalk.com/openapi.yaml, om uw eigen tools te voeden (Postman, Insomnia, contracttests, CI/CD)
API-documentatie in de standaardindeling van de markt
Vanaf de eerste dag kunnen onze klanten en partners het platform met de Raisetalk-API in hun eigen tools integreren: gesprekken uploaden voor analyse, transcripties en analyses ophalen, beoordelingsformulieren voor Quality Monitoring en stem van de klant beheren, realtime callbacks, enzovoort.
Tot nu toe stond de documentatie op een statische pagina, met het bekende risico: documentatie die afdrijft van de code. Een hernoemde parameter, een toegevoegd veld, een endpoint dat wordt uitgefaseerd, en de kloof is er.
We hebben deze documentatie omgezet naar een OpenAPI-specificatie, de feitelijke standaard om een REST-API te beschrijven. En vooral: die specificatie wordt automatisch gegenereerd uit de broncode van de API en bij elke deployment gepubliceerd. De documentatie die u leest, geeft precies het gedrag van de endpoints in productie weer.
Wat dit verandert voor uw integraties
Geen enkele afwijking tussen documentatie en werkelijkheid
Elke deployment genereert de spec opnieuw. Wordt er een veld toegevoegd, een parameter hernoemd of een endpoint uitgefaseerd, dan verwerkt de documentatie dat meteen. U hoeft de samenhang niet meer met de hand te controleren, en tickets als “de documentatie klopt niet met wat de API teruggeeft” zijn verleden tijd.
Een SDK in de programmeertaal van uw keuze, met één commando
Op basis van het bestand openapi.yaml genereert de opensourcetool openapi-generator-cli (onderhouden door de community OpenAPI Tools) een werkende client in meer dan 50 doeltalen: PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust enz. Voorbeeld voor 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
Voor een andere doeltaal vervangt u gewoon de waarde van de parameter -g. Bijvoorbeeld:
| Taal | Parameter -g |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
De volledige lijst van beschikbare generatoren en de configuratieopties staan beschreven op de officiële website: openapi-generator.tech.
Een spec die uw bestaande tools kunnen gebruiken
Het bestand openapi.yaml kunt u rechtstreeks importeren in de meeste API-tools: Postman, Insomnia, Bruno, maar ook in contracttests (Pact, Dredd, Schemathesis), proxy's en gateways (Kong, Tyk) of uw CI/CD-pipelines, om contractbreuken tussen twee versies automatisch op te sporen.
Zo verkent u de documentatie
Ga naar api.raisetalk.com/docs: elk endpoint wordt er gepresenteerd met zijn parameters, typische responses, mogelijke foutcodes en voorbeelden van payloads. In de interface kunt u de endpoints ook rechtstreeks vanuit de browser uitproberen, met uw Bearer-token.
De pagina API-documentatie op onze website verwijst nu rechtstreeks naar deze spec, en naar het bestand openapi.yaml als u het voor uw eigen tools wilt ophalen.
Verder lezen
- De OpenAPI-documentatie ontdekken: api.raisetalk.com/docs
- Het specificatiebestand ophalen: api.raisetalk.com/openapi.yaml
- Een SDK genereren: openapi-generator.tech
- Een integratiecase bespreken: neem contact met ons op
Een automatisch gegenereerde OpenAPI-specificatie publiceren is geen technisch detail: het is een verbintenis tot betrouwbare documentatie en een open platform. Voor uw technische teams is het de zekerheid dat wat in de documentatie staat ook echt in productie draait, en dat een werkende SDK maar één commando verwijderd is.
