L'essenziale sulla documentazione OpenAPI
- La documentazione dell'API Raisetalk è ora pubblicata in formato OpenAPI, accessibile all'indirizzo api.raisetalk.com/docs
- Viene generata automaticamente a partire dal codice sorgente dell'API e aggiornata a ogni rilascio: nessuno scostamento tra la documentazione e il comportamento reale degli endpoint
- Un SDK client può essere generato con un solo comando in quasi tutti i linguaggi più diffusi (PHP, Python, TypeScript, Java, Go, Ruby, C#, ecc.) tramite lo strumento open source
openapi-generator-cli - Il file di specifica grezzo è accessibile anche all'indirizzo api.raisetalk.com/openapi.yaml per alimentare i vostri strumenti (Postman, Insomnia, test di contratto, CI/CD)
Una documentazione API nel formato standard del mercato
Fin dal primo giorno, l'API Raisetalk permette ai nostri clienti e partner di integrare la piattaforma nei propri strumenti: caricamento delle conversazioni da analizzare, recupero delle trascrizioni e delle analisi, gestione delle griglie di valutazione di Quality Monitoring / Voce del Cliente, callback in tempo reale, ecc.
Finora la documentazione viveva in una pagina statica, esposta al rischio classico: la documentazione che si allontana dal codice. Un parametro rinominato, un campo aggiunto, un endpoint deprecato, e lo scarto si insinua.
Abbiamo trasferito questa documentazione in una specifica OpenAPI, lo standard de facto per descrivere un'API REST. E soprattutto: questa specifica è generata automaticamente a partire dal codice sorgente dell'API, poi pubblicata a ogni rilascio. La documentazione che leggete riflette esattamente il comportamento degli endpoint in produzione.
Che cosa cambia per le vostre integrazioni
Zero scostamenti tra la documentazione e la realtà
Ogni rilascio rigenera la specifica. Se viene aggiunto un campo, rinominato un parametro o deprecato un endpoint, la documentazione ne tiene conto immediatamente. Niente più verifiche manuali di coerenza, niente più ticket del tipo «la documentazione non corrisponde a ciò che restituisce l'API».
Un SDK nel linguaggio che preferite, con un solo comando
A partire dal file openapi.yaml, lo strumento open source openapi-generator-cli (mantenuto dalla community OpenAPI Tools) genera un client funzionante in oltre 50 linguaggi di destinazione: PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust, ecc. Esempio per 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
Per cambiare linguaggio di destinazione, basta sostituire il valore del parametro -g. Per esempio:
| Linguaggio | Parametro -g |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
L'elenco completo dei generatori disponibili e le opzioni di configurazione sono documentati sul sito ufficiale: openapi-generator.tech.
Una specifica utilizzabile dai vostri strumenti esistenti
Il file openapi.yaml può essere importato direttamente nella maggior parte degli strumenti per API: Postman, Insomnia, Bruno, ma anche negli strumenti di test di contratto (Pact, Dredd, Schemathesis), nei proxy e gateway (Kong, Tyk) o ancora nelle vostre pipeline CI/CD, per rilevare automaticamente le rotture di contratto tra due versioni.
Come esplorare la documentazione
Andate su api.raisetalk.com/docs: ogni endpoint è presentato con i suoi parametri, le risposte tipo, i possibili codici di errore ed esempi di payload. L'interfaccia permette anche di provare gli endpoint direttamente dal browser, con il vostro token Bearer.
La pagina Documentazione API del nostro sito rimanda ora direttamente a questa specifica, oltre che al file openapi.yaml, se desiderate scaricarlo per i vostri strumenti.
Per approfondire
- Scoprire la documentazione OpenAPI: api.raisetalk.com/docs
- Scaricare il file di specifica: api.raisetalk.com/openapi.yaml
- Generare un SDK: openapi-generator.tech
- Parlare di un caso di integrazione: contattateci
Pubblicare una specifica OpenAPI generata automaticamente non è solo un dettaglio di ingegneria: è un impegno sull'affidabilità della documentazione e sull'apertura della piattaforma. Per i vostri team tecnici è la garanzia che ciò che descrive la documentazione è proprio ciò che gira in produzione, e che un SDK funzionante è a un solo comando di distanza.
