¿Sigue siendo necesario OpenAPI / Swagger si usas SDD con Claude Code?
Con Claude Code generando código a partir de specs, ¿tiene sentido mantener contratos OpenAPI? La respuesta es sí — y además son complementarios. OpenAPI sigue siendo el estándar de contrato entre equipos.
La respuesta directa: son complementarios
SDD con Claude Code y OpenAPI no son excluyentes. Responden a preguntas distintas en el proceso de desarrollo de software:
SDD + Claude Code responde a:
"¿Cómo implementamos este comportamiento? ¿Cuáles son los criterios de aceptación, los edge cases y las reglas de negocio?"
OpenAPI responde a:
"¿Cuál es el contrato de la interfaz? ¿Qué endpoints existen, qué parámetros aceptan y qué respuestas devuelven?"
Cuando el contrato OpenAPI vive en el mismo repositorio que el código, el agente puede leerlo como contexto durante la implementación — convirtiéndolo en una fuente de verdad activa, no en documentación estática que se desactualiza.
Mitos frecuentes cuando se adopta SDD
Mito: "Claude Code puede inferir el contrato de la implementación existente"
Realidad: Puede hacerlo, pero el contrato inferido no está versionado, no está acordado con el equipo consumidor y no genera mocks automáticamente. No es un sustituto.
Mito: "El spec SDD ya describe la API, así que OpenAPI es redundante"
Realidad: El spec SDD describe el comportamiento para el agente. El contrato OpenAPI describe la interfaz para los consumidores externos. Son audiencias distintas con formatos distintos.
Mito: "Mantener el YAML de OpenAPI es overhead innecesario"
Realidad: Cuando el YAML vive en el mismo repositorio, el agente puede leerlo como contexto. Lejos de ser overhead, se convierte en una fuente de verdad que el propio agente consume.
Qué aporta OpenAPI que SDD no cubre
El YAML en el repositorio: cómo el agente lo usa
La recomendación es mantener el contrato OpenAPI dentro del mismo repositorio del servicio — típicamente enapi/openapi.yamlodocs/api.yaml. Esto permite que el agente lo lea como parte del contexto del proyecto cuando el CLAUDE.md hace referencia explícita a él.
# api/openapi.yaml — contrato versionado en el repositorio
openapi: 3.1.0
info:
title: Inventory API
version: 2.1.0
paths:
/stock/{sku}:
get:
summary: Consultar stock disponible
parameters:
- name: sku
in: path
required: true
schema:
type: string
example: ABC-123
responses:
'200':
description: Stock consultado correctamente
content:
application/json:
schema:
$ref: '#/components/schemas/StockResponse'
'404':
description: SKU no encontrado
components:
schemas:
StockResponse:
type: object
required: [sku, available]
properties:
sku:
type: string
available:
type: integer
minimum: 0
reserved:
type: integer
minimum: 0Una vez el YAML está en el repositorio, el CLAUDE.md puede referenciar el contrato como fuente de verdad para el agente — de forma que cualquier implementación respete el esquema sin que el desarrollador tenga que recordarlo explícitamente en cada ticket:
# CLAUDE.md — fragmento de referencia al contrato
## Fuentes de verdad
- Contrato de API: `api/openapi.yaml` (OpenAPI 3.1)
- Antes de implementar cualquier endpoint, leer el contrato.
- Si el contrato y la spec del ticket difieren, escalar al tech lead.
- No añadir campos a la respuesta que no estén en el esquema.
## Proceso de cambio de contrato
1. Actualizar `api/openapi.yaml` con los nuevos campos o endpoints
2. Actualizar el spec SDD del ticket con los criterios de aceptación
3. Regenerar los tipos TypeScript con `npm run gen:types`
4. El agente usa los tipos generados — no los escribe a manoFlujo recomendado: API-first + SDD
Diseñar el contrato primero (API-first)
El tech lead o el equipo diseña los endpoints y esquemas en OpenAPI antes de abrir tickets de implementación. El contrato es el acuerdo entre equipos.
Escribir el spec SDD referenciando el contrato
El criterio de aceptación del ticket incluye: "la implementación debe cumplir el contrato definido en api/openapi.yaml para el endpoint GET /stock/{sku}".
Generar tipos y mocks automáticamente
Usar openapi-typescript o similar para generar los tipos del proyecto. El agente usa esos tipos — no los reescribe.
El agente implementa con el contrato como contexto
El CLAUDE.md referencia el YAML. El agente lo lee, entiende el esquema esperado y produce una implementación coherente con el contrato sin desviarse.
CI verifica el contrato
Herramientas como Spectral (linting de OpenAPI) o Prism (mock server + validación) comprueban en el pipeline que la implementación no rompe el contrato.
Conclusión: OpenAPI y SDD se potencian mutuamente. El contrato YAML define la interfaz pública; el spec SDD define el comportamiento interno. Cuando el YAML vive en el repositorio y el CLAUDE.md lo referencia, el agente tiene acceso a la fuente de verdad completa y produce implementaciones más precisas y consistentes con lo acordado entre equipos.
Referencias
¿Quieres aplicar esto en tu equipo?
En Kuuli Technologies llevamos estas metodologías a equipos reales. Escríbenos si quieres una sesión de trabajo o una consultoría sobre agentes IA y SDD.