Lo esencial sobre la documentación OpenAPI
- La documentación de la API de Raisetalk se publica ahora en formato OpenAPI, disponible en api.raisetalk.com/docs
- Se genera automáticamente a partir del código fuente de la API y se actualiza en cada despliegue: sin desvío entre la documentación y el comportamiento real de los endpoints
- Un SDK cliente puede generarse en un solo comando en prácticamente cualquier lenguaje habitual (PHP, Python, TypeScript, Java, Go, Ruby, C#, etc.) mediante la herramienta open source
openapi-generator-cli - El archivo de especificación en bruto también está accesible en api.raisetalk.com/openapi.yaml para alimentar sus propias herramientas (Postman, Insomnia, tests de contrato, CI/CD)
Una documentación API en el formato estándar del mercado
La API de Raisetalk permite, desde el primer día, a nuestros clientes y partners integrar la plataforma en sus propias herramientas: envío de conversaciones para analizar, recuperación de las transcripciones y análisis, gestión de las rejillas de Quality Monitoring / Voz del Cliente, callbacks en tiempo real, etc.
Hasta ahora, la documentación vivía como una página estática, expuesta al riesgo clásico: la documentación que se desvía del código. Un parámetro renombrado, un campo añadido, un endpoint obsoleto, y la brecha se instala.
Hemos migrado esta documentación hacia una especificación OpenAPI, el estándar de facto para describir una API REST. Y sobre todo: esta especificación se genera automáticamente a partir del código fuente de la API y se publica en cada despliegue. La documentación que lee refleja exactamente el comportamiento de los endpoints en producción.
Qué cambia para sus integraciones
Cero desvío entre documentación y realidad
Cada despliegue regenera la especificación. Si se añade un campo, se renombra un parámetro o se obsoleta un endpoint, la documentación lo refleja de inmediato. Se acabaron las comprobaciones manuales de coherencia y los tickets del tipo "la documentación no coincide con lo que devuelve la API".
Un SDK en el lenguaje de su elección, en un solo comando
A partir del archivo openapi.yaml, la herramienta open source openapi-generator-cli (mantenida por la comunidad OpenAPI Tools) genera un cliente funcional en más de 50 lenguajes de destino: PHP, Python, TypeScript, Java, Go, Ruby, C#, Kotlin, Swift, Rust, etc. Ejemplo para 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
Para cambiar el lenguaje de destino, basta con modificar el valor del parámetro -g. Por ejemplo:
| Lenguaje | Parámetro -g |
|---|---|
| PHP | php |
| Python | python |
| TypeScript (axios) | typescript-axios |
| Java | java |
| Go | go |
| Ruby | ruby |
| C# | csharp |
La lista completa de generadores disponibles, así como las opciones de configuración, están documentadas en el sitio oficial: openapi-generator.tech.
Una especificación utilizable por sus herramientas existentes
El archivo openapi.yaml puede importarse directamente en la mayoría de las herramientas de API: Postman, Insomnia, Bruno, pero también en los tests de contrato (Pact, Dredd, Schemathesis), los proxies y gateways (Kong, Tyk) o en sus pipelines de CI/CD para detectar automáticamente las rupturas de contrato entre dos versiones.
Cómo explorar la documentación
Diríjase a api.raisetalk.com/docs: cada endpoint se presenta con sus parámetros, respuestas tipo, códigos de error posibles y ejemplos de payload. La interfaz permite además probar los endpoints directamente desde el navegador, con su token Bearer.
La página Documentación API de nuestro sitio remite ahora directamente a esta especificación, así como al archivo openapi.yaml si desea recuperarlo para sus propias herramientas.
Para ir más lejos
- Descubrir la documentación OpenAPI: api.raisetalk.com/docs
- Obtener el archivo de especificación: api.raisetalk.com/openapi.yaml
- Generar un SDK: openapi-generator.tech
- Hablar sobre un caso de integración: póngase en contacto con nosotros
Publicar una especificación OpenAPI generada automáticamente no es solo un detalle de ingeniería: es un compromiso con la fiabilidad de la documentación y con la apertura de la plataforma. Para sus equipos técnicos, significa la garantía de que lo descrito en la documentación corresponde exactamente a lo que corre en producción, y que un SDK funcional está a un solo comando de distancia.
