02 - API First

La API es el contrato entre una aplicación y quienes la consumen. Define operaciones, datos de entrada y salida y respuestas posibles. Este tema se centra en el contrato HTTP; la misma idea de contrato explícito aplica a la comunicación entre módulos internos, que se desarrolla en el tema 04.

Los DTO de entrada y salida describen los datos que cruzan la frontera HTTP: se diseñan para el contrato y no tienen por qué coincidir con los modelos internos. La validación del formato de la solicitud —campos obligatorios, formatos, longitudes— se declara con Jakarta Bean Validation (@NotBlank, @Email, @Size y @Valid) y corresponde a la capa de presentación; las reglas de negocio siguen perteneciendo al dominio. La validación completa de la entrada, con sus invariantes, se desarrolla en el tema 03.

Enfoque Punto de partida Uso del contrato
API First Se diseña el contrato antes de implementar Guía y permite acordar el trabajo de clientes y servidor
Code First Se implementa primero El contrato se deriva después del código, por ejemplo, con anotaciones

API First hace explícitas las decisiones de interfaz y permite revisarlas antes de implementarlas. El contrato describe lo que necesita el cliente; no expone automáticamente los modelos internos.

Diseñar contratoRevisar y acordarImplementar APIComprobar contrato

OpenAPI es una especificación para describir APIs HTTP en YAML o JSON. Define rutas y operaciones, parámetros, esquemas de datos, respuestas y restricciones.

Swagger es un conjunto de herramientas para trabajar con OpenAPI. Por ejemplo, Swagger UI presenta el contrato como documentación interactiva.

Este fragmento define una solicitud y dos respuestas de una operación:

paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created
        '400':
          description: Invalid request

El contrato HTTP y el código que implementa sus operaciones son responsabilidades relacionadas, pero pueden mantenerse separados. En Spring, springdoc-openapi genera un documento OpenAPI y Swagger UI a partir de las anotaciones del código.

Una opción es declarar rutas, parámetros y documentación en una interfaz Java como OrderHttpApi, y dejar que OrderController implemente sus operaciones. El nombre indica que es el contrato HTTP, distinto de una API interna que un módulo pueda ofrecer a otros módulos:

@Tag(name = "Orders")
public interface OrderHttpApi {
    @Operation(summary = "Create an order")
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "Order created"),
        @ApiResponse(responseCode = "400", description = "Invalid request")
    })
    @PostMapping("/orders")
    ResponseEntity<OrderResponse> create(
            @Valid @RequestBody CreateOrderRequest request);
}
 
@RestController
public class OrderController implements OrderHttpApi {
    @Override
    public ResponseEntity<OrderResponse> create(CreateOrderRequest request) {
        // Delegar la operación y producir la respuesta.
    }
}

Así se separan las declaraciones del contrato HTTP de la lógica del controlador y springdoc-openapi puede generar la documentación. La interfaz puede diseñarse antes de implementar el controlador y formar parte de un flujo API First, pero queda ligada al código Java; el documento generado no es una especificación independiente del código.

Otra opción es mantener una especificación OpenAPI en un archivo, por ejemplo orders-api.yaml, como fuente de verdad antes de implementar. Es útil para revisar el contrato con consumidores y trabajar en paralelo. Además, a partir de esa especificación se puede generar parte del código Java:

Fuente del contratoInterfaz JavaArchivo OpenAPIInterfaz Java + anotacionesspringdoc-openapiDocumento OpenAPI y Swagger UIorders-api.yamlOpenAPI Generator(plugin de Maven)Interfaces API + DTOsgeneradosEl Controller implementala interfaz generada

En este segundo flujo, OpenAPI Generator lee orders-api.yaml y genera las interfaces de la API y las clases de modelo —los DTO— definidos en el contrato. El plugin de Maven suele ejecutar esta generación en la fase generate-sources, antes de compilar el proyecto. Por ejemplo, al ejecutar mvn compile, Maven recorre las fases anteriores e invoca la generación si el plugin está configurado para ello.

Las clases generadas suelen quedar en una carpeta como target/generated-sources/openapi, aunque la ruta depende de la configuración. No siempre aparecen entre los archivos escritos a mano: puede ser necesario ejecutar Maven y actualizar el proyecto en el IDE para que las muestre. Se pueden consultar, pero no se deben modificar directamente; si cambia el contrato, se vuelve a generar el código.

El equipo implementa las operaciones de las interfaces generadas en sus Controller. En resumen, con springdoc-openapi se obtiene documentación OpenAPI a partir del código Spring; con OpenAPI Generator se obtiene código Java a partir del archivo OpenAPI.

Fuente del contrato Ventaja Precaución
Interfaz Java OrderHttpApi y anotaciones Contrato y documentación junto a la interfaz HTTP; documentación generada desde Spring Se define desde el código; los cambios requieren revisar el contrato resultante
Archivo orders-api.yaml y OpenAPI Generator Contrato independiente; permite generar interfaces API y DTOs Configurar el generador y comprobar que la implementación sigue la especificación

Elegir una fuente de verdad evita mantener dos contratos manuales que puedan divergir. En ambos enfoques, los DTO HTTP describen los datos públicos y se mapean a modelos internos; no se exponen directamente los modelos del dominio.

Un cambio es incompatible si obliga a los consumidores a cambiar sus solicitudes o cómo interpretan las respuestas. Eliminar un campo, cambiar su tipo o alterar el significado de una respuesta puede romper clientes.

Al revisar cambios, comprobar:

  • Que operaciones, datos y respuestas describen el comportamiento público.
  • Que restricciones y errores son claros para quien consume la API.
  • Que los cambios no rompen compatibilidad sin una transición acordada.

Se puede validar la sintaxis OpenAPI, comparar versiones y comprobar solicitudes y respuestas de la implementación. Las pruebas HTTP de controller verifican el comportamiento integrado; abrir Swagger UI no demuestra por sí solo la conformidad. Si se usa un archivo OpenAPI como fuente, hay que comprobar que la implementación se ajusta a él.

OpenAPI describe el contrato; Swagger UI ayuda a explorarlo. La documentación no sustituye el diseño, la revisión de compatibilidad ni las pruebas.
  • clase/daw/dws/api_first.txt
  • Última modificación: 2026/11/08 10:10
  • por cesguiro