Java Spring Boot & SDD: Implementando el Flujo Contract-First con OpenAPI

n el artículo anterior, exploramos la teoría del Spec-Driven Development (SDD). Hoy vamos a ensuciarnos las manos con la implementación técnica en el lado del servidor. Si eres un desarrollador Java, sabes que escribir DTOs, mappers y controladores manualmente es una tarea repetitiva y propensa a errores.

Implementar un flujo Contract-First en Java Spring Boot no solo acelera el desarrollo, sino que garantiza que tu API sea un reflejo exacto de lo que se acordó en el diseño.

1. El Punto de Partida: El archivo openapi.yaml

En SDD, el código comienza en un archivo de especificación. Imaginemos que estamos construyendo un módulo de gestión de usuarios para J Code Solutions. Nuestro archivo openapi.yaml (ubicado usualmente en src/main/resources/api-spec/) se vería así:

YAML

openapi: 3.0.3
info:
title: User Management API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Obtener un usuario por ID
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Usuario encontrado
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
components:
schemas:
UserResponse:
type: object
properties:
id:
type: string
format: uuid
fullName:
type: string
email:
type: string
format: email

2. Automatización con OpenAPI Generator

Para que este YAML se convierta en código Java real, utilizaremos el plugin de OpenAPI Generator. En tu archivo build.gradle (o pom.xml si usas Maven), debemos configurar la tarea de generación.

Configuración en Gradle:

Gradle

plugins {
id 'org.openapi.generator' version '7.2.0'
}

openApiGenerate {
generatorName = "spring"
inputSpec = "$projectDir/src/main/resources/api-spec/openapi.yaml".toString()
outputDir = "$buildDir/generated".toString()
apiPackage = "com.jcodesolutions.api"
modelPackage = "com.jcodesolutions.model"
configOptions = [
interfaceOnly: "true",
useSpringBoot3: "true",
useTags: "true",
skipDefaultInterface: "true"
]
}

sourceSets.main.java.srcDir "$buildDir/generated/src/main/java"

¿Por qué interfaceOnly: "true"? Esta es la clave para un desarrollador Senior. No queremos que el plugin genere todo el proyecto, solo las interfaces de los controladores y los DTOs (Data Transfer Objects). De esta forma, el programador mantiene el control total sobre la implementación de la lógica de negocio.

3. Implementando la Interfaz Generada

Una vez que ejecutas ./gradlew openApiGenerate, el plugin creará por ti una interfaz llamada UsersApi. Tu trabajo ahora es simplemente crear un @RestController que la implemente:

Java

@RestController
public class UserController implements UsersApi {

@Override
public ResponseEntity<UserResponse> getUsersId(UUID id) {
// Aquí llamarías a tu servicio (Service Layer)
UserResponse response = new UserResponse()
.id(id)
.fullName("Joan Sebastian")
.email("contacto@jcodesolutions.com");

return ResponseEntity.ok(response);
}
}

Si intentas cambiar el nombre del campo fullName por name, el proyecto no compilará. El contrato te obliga a ser consistente.

4. Ventajas para la Infraestructura y el Equipo

Al trabajar así, facilitamos enormemente la vida de otros departamentos:

• Persistencia (PostgreSQL): Al tener DTOs claros, el mapeo hacia nuestras entidades de base de datos es mucho más predecible.
• Documentación Viva: Al integrar SpringDoc OpenAPI, tu servidor expondrá automáticamente una interfaz de Swagger UI siempre actualizada en /swagger-ui.html.
• Contratos para el Frontend: El equipo de Next.js puede tomar este mismo archivo YAML y generar sus propios clientes API, asegurando que ambos mundos hablen el mismo idioma.

5. Conclusión Técnica

Implementar SDD en Java Spring Boot eleva el estándar de calidad de cualquier proyecto. Elimina la "adivinación" en el desarrollo de APIs y permite que los errores de integración se detecten en tiempo de compilación, no en producción.