API Gateway, API-First Design y Contratos OpenAPI 3.1

spring:
  cloud:
    gateway:
      default-filters:
        - AddResponseHeader=X-Content-Type-Options, nosniff
      routes:
        - id: tareas
          uri: http://tareas-service:8080
          predicates:
            - Path=/api/tareas/**
          filters:
            - name: CircuitBreaker
              args:
                name: tareas
                fallbackUri: forward:/fallback/tareas

        - id: usuarios-v2
          uri: http://usuarios-service-v2:8080
          predicates:
            - Path=/api/v2/usuarios/**
          filters:
            - StripPrefix=2                    # /api/v2/usuarios/7 -> /usuarios/7
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 20
                redis-rate-limiter.burstCapacity: 40

# src/main/resources/api/tareas.yaml
openapi: 3.1.0
info: { title: Tareas, version: 1.0.0 }
paths:
  /tareas/{id}:
    get:
      operationId: obtenerTarea
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        "200":
          description: La tarea
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Tarea" }
        "404": { description: No existe }
components:
  schemas:
    Tarea:
      type: object
      required: [id, titulo]
      properties:
        id: { type: integer, format: int64 }
        titulo: { type: string, maxLength: 120 }

# pom.xml (resumen)
# <plugin> org.openapitools:openapi-generator-maven-plugin
#   <inputSpec>src/main/resources/api/tareas.yaml</inputSpec>
#   <generatorName>spring</generatorName>
#   <configOptions><interfaceOnly>true</interfaceOnly><useSpringBoot3>true</useSpringBoot3></configOptions>
# -> genera TareasApi (interfaz) y Tarea (modelo); tu @RestController implementa TareasApi

// pom.xml: org.springdoc:springdoc-openapi-starter-webmvc-ui

@RestController
@RequestMapping("/api/tareas")
@Tag(name = "Tareas", description = "Gestión de tareas de un proyecto")
class TareaController {

    @Operation(summary = "Obtener una tarea por id")
    @ApiResponse(responseCode = "200", description = "Tarea encontrada")
    @ApiResponse(responseCode = "404", description = "No existe",
        content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
    @GetMapping("/{id}")
    TareaResponse obtener(@Parameter(description = "Id de la tarea", example = "42")
                          @PathVariable long id) {
        return servicio.obtener(id);
    }
}

// application.yml
// springdoc:
//   api-docs.path: /v3/api-docs
//   swagger-ui.path: /swagger-ui.html
//   swagger-ui.enabled: ${SWAGGER_UI:false}     # desactivado salvo que se pida

@Component
class CorrelacionFilter implements GlobalFilter, Ordered {

    private static final String CABECERA = "X-Correlation-Id";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String id = Optional.ofNullable(exchange.getRequest().getHeaders().getFirst(CABECERA))
            .orElseGet(() -> UUID.randomUUID().toString());

        ServerWebExchange conId = exchange.mutate()
            .request(r -> r.header(CABECERA, id))          // hacia el servicio
            .build();
        conId.getResponse().getHeaders().add(CABECERA, id); // hacia el cliente

        long inicio = System.nanoTime();
        return chain.filter(conId)
            .doFinally(s -> log.info("{} {} -> {} en {} ms [{}]",
                exchange.getRequest().getMethod(), exchange.getRequest().getPath(),
                conId.getResponse().getStatusCode(),
                (System.nanoTime() - inicio) / 1_000_000, id));
    }

    @Override
    public int getOrder() { return Ordered.HIGHEST_PRECEDENCE; }
}

@RestController
@RequestMapping("/api/v1/tareas")
class TareaControllerV1 {
    @GetMapping("/{id}")
    ResponseEntity<TareaV1> obtener(@PathVariable long id) {
        return ResponseEntity.ok()
            .header("Deprecation", "@1767225600")                  // obsoleta desde 2026-01-01
            .header("Sunset", "Wed, 01 Jul 2026 00:00:00 GMT")     // se retira en esta fecha
            .header("Link", "</api/v2/tareas/" + id + ">; rel=\"successor-version\"")
            .body(TareaV1.desde(servicio.obtener(id)));
    }
}

@RestController
@RequestMapping("/api/v2/tareas")
class TareaControllerV2 {
    @GetMapping("/{id}")
    TareaV2 obtener(@PathVariable long id) {          // v2: "estado" sustituye al booleano "completada"
        return TareaV2.desde(servicio.obtener(id));
    }
}