¿Qué es el Desarrollo de APIs Spec-First?

La mayoría de los errores de API no son errores de codificación. Son errores de acuerdo. El frontend esperaba userId, el backend envió user_id, y nadie lo notó hasta control de calidad. El desarrollo de API basado en la especificación (spec-first) lo soluciona haciendo que el contrato sea lo primero que escribes, no lo último que documentas.

En esta guía, escribirás una pequeña especificación OpenAPI a mano, luego usarás ese único archivo para generar mocks, pruebas y documentación antes de que exista cualquier código de servidor. El mismo enfoque se conoce con algunos nombres: desarrollo dirigido por especificaciones (spec-driven development), diseño primero (design-first) o contrato primero (contract-first). Todos apuntan a la misma idea. Ponte de acuerdo en la interfaz primero y luego construye sobre ella.

Qué es el desarrollo de API basado en la especificación

El desarrollo de API basado en la especificación significa que creas un contrato legible por máquina, generalmente un documento OpenAPI, antes de implementar el endpoint. Ese contrato describe cada ruta, parámetro, cuerpo de solicitud, forma de respuesta y código de estado. Una vez que existe, se convierte en la fuente de verdad para todos los que trabajan con la API.

La especificación no es documentación que va por detrás del código. Lidera. Los equipos de frontend construyen sobre un mock generado a partir de ella. Control de calidad escribe pruebas contra ella. El backend implementa para satisfacerla. Cuando los tres están de acuerdo con el mismo archivo, la integración deja de ser un juego de adivinanzas.

Esto invierte el orden habitual. En el desarrollo code-first, escribes los manejadores y luego los describes, a menudo a mano, a menudo desactualizados en un sprint. En un flujo de trabajo design-first, la descripción viene primero y el código responde a ella. Ese único cambio traslada la mayoría de los problemas de integración al inicio del proyecto, donde son baratos de solucionar.

Ciclo de vida spec-first vs code-first

Ambos enfoques producen los mismos endpoints. Difieren en cuándo surgen los problemas y quién puede comenzar a trabajar en paralelo.

La columna de la derecha es la recompensa. Cuando el contrato existe primero, tres equipos dejan de bloquearse entre sí y comienzan a construir a partir de una definición compartida.

Un ejemplo de OpenAPI práctico

Diseñemos un pequeño endpoint /users paso a paso. Lo construiremos en partes para que cada una sea clara, y luego ensamblaremos el archivo completo.

Comienza con la cabecera del documento. Esto declara la versión de OpenAPI y los metadatos básicos.

openapi: 3.0.3
info:
 title: API de Usuarios
 version: 1.0.0
servers:
 - url: https://api.example.com/v1

A continuación, define el esquema User bajo components. Definirlo una vez te permite referenciarlo en todas partes, de modo que la forma se mantiene coherente en todas las solicitudes y respuestas.

components:
 schemas:
 User:
 type: object
 required: [id, email, createdAt]
 properties:
 id:
 type: string
 format: uuid
 email:
 type: string
 format: email
 name:
 type: string
 createdAt:
 type: string
 format: date-time

Ahora añade la ruta GET /users. Enumera usuarios y admite un parámetro de consulta limit. Observa cómo la respuesta reutiliza el esquema User con $ref en lugar de redefinirlo.

paths:
 /users:
 get:
 summary: Listar usuarios
 operationId: listUsers
 parameters:
 - name: limit
 in: query
 schema:
 type: integer
 default: 20
 maximum: 100
 responses:
 "200":
 description: Una lista de usuarios
 content:
 application/json:
 schema:
 type: array
 items:
 $ref: "#/components/schemas/User"

Añade la operación POST /users para crear un usuario. El cuerpo de la solicitud define lo que el cliente debe enviar, y la respuesta 201 devuelve el registro creado.

 post:
 summary: Crear un usuario
 operationId: createUser
 requestBody:
 required: true
 content:
 application/json:
 schema:
 type: object
 required: [email]
 properties:
 email:
 type: string
 format: email
 name:
 type: string
 responses:
 "201":
 description: Usuario creado
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/User"
 "400":
 description: Cuerpo de solicitud inválido

Ese es un contrato completo y válido. Nombra cada campo, marca email como requerido, limita limit a 100 y declara tanto las respuestas de éxito como las de error. Nadie ha escrito aún una línea de código de servidor, pero el acuerdo está cerrado.

Generar mocks, pruebas y documentación a partir de la especificación

La razón para escribir la especificación primero es la influencia. Un solo archivo impulsa tres artefactos que los equipos suelen construir por separado.

Mocks. Un servidor mock lee tu especificación y devuelve respuestas de ejemplo que coinciden con cada esquema. Las pistas format: uuid y format: email permiten a las herramientas generar datos de ejemplo realistas. Tu frontend llama a GET /users y obtiene un array de usuarios bien formado el primer día, mucho antes de que exista el manejador real. Cuando la especificación cambia, el mock cambia con ella.

Pruebas. Debido a que la especificación declara campos requeridos, tipos y códigos de estado, funciona como un oráculo de pruebas. Las pruebas de contrato afirman que la respuesta real para POST /users devuelve un 201 con un cuerpo que coincide con el esquema User, y un 400 cuando falta email. No estás inventando aserciones. Estás comprobando que la implementación coincide con lo que ya acordaste.

Documentación. La documentación de referencia de la API se genera directamente a partir de la especificación. Cada endpoint, parámetro y ejemplo que ves en la documentación proviene del mismo YAML. No hay una segunda copia que mantener sincronizada, por lo que la documentación no puede desviarse del contrato.

Esto también es lo que hace que el enfoque spec-first combine bien con un flujo de trabajo de API nativo de Git: la especificación es un archivo de texto plano, por lo que cada cambio en el contrato aparece como un diff revisable en una solicitud de extracción. Un revisor puede ver que alguien cambió el nombre de email o eliminó un campo requerido antes de que se implemente.

Haciéndolo en Apidog

Apidog soporta esto de principio a fin a través del Modo Spec-First. En lugar de tratar el archivo OpenAPI como una exportación, lo trata como el proyecto. Editas el YAML directamente y el resto del espacio de trabajo lo sigue.

Escribes o pegas la especificación /users en el editor. Apidog la parsea e inmediatamente levanta un servidor mock para ambas operaciones, para que tu frontend pueda empezar a llamarlas. La documentación generada se actualiza a medida que escribes. Cuando estés listo para verificar la implementación, ejecutas las operaciones de la especificación como casos de prueba contra tu backend real y confirmas que las respuestas coinciden con los esquemas.

La parte que mantiene esto honesto es la sincronización bidireccional de Git. Tu especificación reside en un repositorio, y los cambios fluyen en ambas direcciones. Edita el YAML en tu editor y haz push, y Apidog lo recoge. Edita en Apidog, y el cambio aterriza como un commit que tu equipo puede revisar. El contrato nunca reside en dos lugares a la vez. Si deseas una comparación más profunda de cómo esto se sitúa junto a un enfoque puramente design-first, consulta spec-first vs design-first en Apidog.

Una lista de verificación spec-first

Usa esto antes de considerar que una especificación está lista para construir sobre ella:

• La especificación se valida contra el esquema OpenAPI sin errores.
• Cada endpoint declara su éxito y al menos una respuesta de error.
• Las formas compartidas residen en components/schemas y se referencian con $ref, no se copian.
• Los campos obligatorios están marcados como required, y los formatos (uuid, email, date-time) se establecen donde corresponda.
• El archivo de especificación está commitado al control de versiones y revisado en solicitudes de extracción.
• Un servidor mock se ejecuta a partir de la especificación, y el frontend puede interactuar con él.
• Las pruebas de contrato verifican las respuestas reales contra los esquemas declarados.
• La documentación publicada se genera a partir del mismo archivo, sin copia mantenida a mano.

Si todas las casillas están marcadas, tus equipos pueden construir en paralelo basándose en un único acuerdo en lugar de tres suposiciones.

Preguntas frecuentes

¿Es lo mismo el desarrollo de API basado en la especificación que el diseño primero?

Mayormente sí. "Diseño primero" y "contrato primero" describen el mismo principio: escribir la interfaz antes de la implementación. "Basado en la especificación" es el nombre más literal porque el archivo de especificación OpenAPI es el artefacto concreto con el que se empieza. En la práctica, los términos se usan indistintamente.

¿Tengo que escribir YAML a mano?

No. Puedes crear la especificación en un editor visual y dejar que produzca el YAML, o escribir el YAML directamente si lo prefieres. El punto no es el formato que escribes, sino que el contrato exista y se acuerde antes del código. Muchos equipos mezclan ambos, diseñando visualmente y refinando en YAML durante la revisión.

¿Cómo evito que la especificación y el código se separen?

Haz de la especificación la fuente de verdad y hazla cumplir. Mantén la especificación en Git para que los cambios se revisen como diferencias. Ejecuta pruebas de contrato en CI para que la compilación falle cuando una respuesta deje de coincidir con el esquema. Con la sincronización bidireccional, las ediciones en cualquier lugar se mantienen conciliadas, lo que elimina la causa más común de desviación.

El desarrollo de API basado en la especificación es un pequeño cambio en el orden con un gran cambio en el resultado. Escribe el contrato, ponte de acuerdo sobre él y luego construye sobre él. Si quieres probar el ciclo completo, abre el Modo Spec-First en Apidog y apúntalo a tu repositorio.