API y software
De un archivo OpenAPI o Swagger a un diagrama de flujo
Un archivo OpenAPI (o Swagger) enumera lo que puede hacer una API, pero no en qué orden la usa un proceso. Para obtener un diagrama útil, combina el archivo con una descripción breve del proceso: la descripción aporta el orden y las decisiones, y la especificación, el endpoint exacto de cada paso automático.
OpenAPI y Swagger en un párrafo
La especificación OpenAPI es un formato estándar, en JSON o YAML, para describir API HTTP: rutas, operaciones, parámetros y respuestas. Nació como especificación Swagger; la versión 2.0 se sigue llamando a menudo «Swagger 2», y el estándar continuó como OpenAPI 3.x. Las herramientas usan estos archivos para generar documentación, clientes y pruebas.
Por qué no basta con la especificación
Una especificación es un catálogo: dice que existen POST /clientes, POST /verificaciones-kyc y POST /cuentas. No dice que el cliente debe pasar la verificación KYC antes de crear la cuenta, ni qué pasa si la verificación falla. Ese orden y esas reglas son el proceso de negocio, y están en la cabeza de las personas o en otros documentos.
El enfoque combinado
- Describe el proceso en unas frases, indicando quién o qué hace cada paso: consulta cómo describir un proceso para la IA.
- Adjunta la especificación (OpenAPI 3 o Swagger 2, en
.json,.yamlo.yml). - Genera: los pasos salen de tu descripción; los pasos automáticos que realiza el sistema se asocian al endpoint más adecuado, que aparece en el paso, como
POST /verificaciones-kyc. - Revisa las asociaciones: comprueba que cada endpoint es el que realmente se llama y corrige cualquier error pidiéndolo, por ejemplo «usa PUT /cuentas/{id} para el paso de activación».
Qué lee Flowchartio del archivo
Flowchartio detecta los archivos OpenAPI y Swagger, enumera sus operaciones como «MÉTODO /ruta» y las usa durante la generación. El límite es de 5 MB por archivo. Otros archivos JSON, YAML y XML se aceptan como contexto, y los servicios SOAP se pueden importar desde su WSDL.
Un ejemplo breve
Descripción: «Un visitante se registra. El sistema crea el cliente y lanza la verificación KYC. Si la verificación falla, se informa al cliente. Si no, el sistema abre la cuenta y envía un correo de bienvenida.» Con una especificación que contenga esos endpoints, el resultado tiene un carril Sistema donde «Crear cliente», «Lanzar verificación KYC», «Abrir cuenta» y «Enviar correo de bienvenida» llevan cada uno su endpoint, además de una decisión sobre el resultado de la verificación.
Aprovecha el resultado
- Compártelo con producto y soporte, que no leen especificaciones.
- Pega la exportación Mermaid en el repositorio, junto a la especificación; consulta Mermaid en GitHub y GitLab.
- Amplíalo hasta una documentación de integración completa con reintentos y errores: documentar un flujo de integración de API.
Convierte tu proceso en un diagrama de flujo
Descríbelo en unas frases. Flowchartio dibuja el diagrama y luego lo ajustas conversando.
Generar un diagrama