openapi · 30 jun 2026, 12:00
Cinco anti-patrones comunes en contratos OpenAPI (y cómo evitarlos)
Errores habituales en el diseño de contratos OpenAPI y prácticas concretas para evitarlos con reglas, revisión y CI.
Cinco anti-patrones comunes en contratos OpenAPI (y cómo evitarlos)
OpenAPI puede ordenar mucho el diseño de una API, pero también puede amplificar malos hábitos si el contrato se escribe sin intención. Muchos equipos caen en los mismos anti‑patrones: especificaciones que parecen útiles en el corto plazo y acaban siendo una fuente constante de fricción.
Aquí repasamos cinco anti‑patrones habituales en contratos OpenAPI y formas concretas de evitarlos con guías de estilo, revisión en equipo y controles automáticos en CI.
1. Contratos centrados en la implementación
Es el error clásico: diseñar el contrato desde la estructura interna (tablas, microservicios, nombres de clases) en lugar de desde la perspectiva del consumidor.
Síntomas típicos:
- Paths que exponen jerarquías internas difíciles de entender.
- Modelos que muestran detalles irrelevantes de la implementación.
- Mensajes de error que hablan en jerga del stack, no del negocio.
La literatura reciente de diseño API recomienda un enfoque outside‑in: pensar primero como integrador y después como desarrollador. En OpenAPI, eso implica revisar nombres de recursos, modelos y errores para que reflejen el dominio funcional, no la estructura de código.
Cómo evitarlo: revisar contratos con personas de frontend, producto y soporte, evitar nombres basados en tablas y documentar modelos según casos de uso reales.
2. Inconsistencia en paths, métodos y códigos de estado
Otro anti‑patrón común es tratar HTTP como un detalle incidental: mezclar singular y plural, usar POST para todo, ignorar reglas de versionado y devolver códigos de estado arbitrarios.
Ejemplos típicos:
- Paths como /getUser o /create-user que mezclan verbos y recursos.
- Uso de POST para operaciones que deberían ser GET o PUT porque son idempotentes.
- Mezclas caprichosas de 200, 201, 204, 400 o 500 sin criterio consistente.
Las buenas prácticas insisten en separar recursos (sustantivos) de acciones y usar métodos y códigos según los estándares HTTP.
Cómo evitarlo: definir una guía de estilo de nombres y métodos, revisar métodos y códigos en cada pull request y añadir reglas de linting que detecten paths con verbos y errores sin estructura.
3. Modelos hinchados y respuestas poco pensadas
Es tentador reutilizar directamente el modelo de base de datos y devolverlo tal cual en cada respuesta. El problema: acabas con payloads enormes, difícilmente mantenibles y muy difíciles de versionar.
Consecuencias habituales:
- Respuestas pesadas que perjudican a clientes móviles o integraciones de baja latencia.
- Campos que nadie usa pero que hay que mantener por compatibilidad.
- Dificultad para introducir nuevas vistas más adaptadas a casos de uso.
Las guías modernas recomiendan diseñar las respuestas pensando en necesidades concretas y usar filtrado, paginación y proyección de campos en lugar de devolver todo.
Cómo evitarlo: modelar schemas según lo que necesitan los consumidores, revisar payloads para reducir ruido y documentar con claridad qué campos son opcionales, para evitar dependencias accidentales.
4. Errores mal estructurados y difíciles de manejar
Otro anti‑patrón clásico: documentar muy poco los errores, mezclar formatos distintos o dejar la forma de los mensajes de error totalmente a la improvisación.
Síntomas:
- Clientes que solo pueden distinguir errores leyendo texto libre.
- Respuestas 4xx/5xx con estructuras distintas según el endpoint.
- Imposibilidad de correlacionar errores con incidentes o logs internos.
Las buenas prácticas insisten en definir un contrato de error consistente (por ejemplo code, message, details, traceId) y reutilizarlo en toda la API.
Cómo evitarlo: definir uno o varios schemas de error estándar en components.schemas, referenciarlos desde todas las respuestas no exitosas y añadir ejemplos claros para cada tipo de error.
5. Sin versión ni política de cambios
El anti‑patrón más peligroso: cambiar contratos sin versionado explícito ni política de deprecación. Si se eliminan campos, se renombrar propiedades o se cambian rutas sin estrategia, los clientes se rompen sin aviso.
Las guías de versionado insisten en distinguir cambios aditivos (compatibles) de cambios incompatibles y tratar estos últimos con mucho más cuidado: versionado claro, ventana de convivencia y migración guiada.
Cómo evitarlo: clasificar cambios entre aditivos y breaking antes de cada release, usar herramientas de diff como oasdiff en CI para detectar breaking changes y definir una política interna de deprecación y retirada.
Cómo usamos Capydox para detectar y corregir estos anti‑patrones
En Capydox trabajamos para que el contrato deje de ser un archivo olvidado y se convierta en parte activa del flujo de equipo. Nuestro editor OpenAPI en el workspace permite revisar el spec con enfoque más centrado en el consumidor, documentar modelos y errores con ejemplos y conectar el contrato con colecciones y documentación enriquecida.
Además, Capydox Desktop y el escáner OpenAPI (ScanAPI) ayudan a recuperar contratos desde código legacy: escaneamos el backend, generamos un OpenAPI 3.1 y lo llevamos al editor para pulirlo, aplicar reglas de estilo y meterlo en pipelines de validación.
El objetivo no es alcanzar una perfección teórica, sino usar OpenAPI como palanca para reducir fricción real en integraciones, documentación y evolución de APIs. Cuando el contrato se cuida, el resto del ecosistema se vuelve más predecible.