La documentación de una API suele escribirse al final, con prisa y desde la memoria. Tres meses después ya no coincide con el comportamiento real, y quien integra el servicio termina leyendo el código o preguntando por chat.
El contrato primero
OpenAPI es una especificación en YAML o JSON que describe los endpoints, los parámetros, los cuerpos de petición y respuesta, los códigos de error y la autenticación. Escribe ese archivo antes de programar. Los equipos de backend y de frontend lo revisan juntos y discuten nombres y formas de error mientras todavía es fácil cambiarlos. Solo entonces se implementa.
Así se ve un endpoint en el archivo, con su respuesta de error incluida:
paths:
/orders/{orderId}:
get:
summary: Consultar un pedido
parameters:
- name: orderId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: El pedido existe
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: No existe un pedido con ese identificador
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: https://api.ejemplo.com/errores/pedido-no-encontrado
title: Pedido no encontrado
status: 404
detail: No existe un pedido con el identificador indicado.
instance: /orders/3f2b8c1e-5a7d-4c3e-9b1a-2d6e8f0a4b7c
traceId: 7c1f0a52-8d3e-4b6a-9e21-5f0c7a3d1b84
Con el contrato acordado, el equipo de frontend no espera a que el servicio exista: genera un servidor simulado (mock) a partir del archivo, con una herramienta como Prism, y avanza con respuestas realistas desde el primer día.
Qué se obtiene del mismo archivo
La especificación alimenta varias cosas a la vez. Herramientas como Swagger UI o Redoc publican una documentación navegable en la que se pueden probar las llamadas. Los generadores de código producen clientes tipados en TypeScript, Java o el lenguaje que use quien consume la API. Las pruebas de contrato comparan las respuestas reales con lo descrito y avisan cuando alguien cambia un campo sin actualizar el archivo.
En proyectos con Spring Boot es habitual generar la especificación desde el código con anotaciones, algo válido si el archivo generado se revisa en cada cambio como parte del code review.
Errores comunes
Uno habitual es documentar solo el camino feliz: las respuestas 400, 401, 404 y 409 con su formato son lo que más necesita saber quien integra. Otro es no versionar, porque un cambio que rompe a los clientes necesita una versión nueva de la API y una entrada en el registro de cambios. Un tercero es publicar ejemplos de relleno, como string o foo, en lugar de valores que se parezcan a los reales.
También es útil definir un formato de error único para todo el servicio. El estándar RFC 9457 (Problem Details) es un buen punto de partida: type identifica de forma estable el tipo de error, title y detail llevan el mensaje y, como extensión, puedes añadir un identificador de petición como traceId para seguir el caso en los registros. La respuesta 404 de arriba ya usa los campos del estándar y esa extensión.
Revisión en el pipeline
Un paso de validación en el pipeline de integración continua, con un linter como Spectral, evita que entre un archivo mal formado o que rompa las reglas del equipo. Montarlo lleva una tarde. La configuración mínima parte de las reglas que ya trae la herramienta:
# .spectral.yaml
extends: ["spectral:oas"]
El paso del pipeline es una sola línea, npx @stoplight/spectral-cli lint openapi.yaml, y falla cuando el archivo incumple una regla.
¿Tienes un servicio sin contrato claro? Cuéntanos qué API integras hoy y escribimos el contrato contigo. En nuestro servicio de desarrollo backend y APIs diseñamos e implementamos APIs REST siguiendo especificaciones OpenAPI.