@ConfigurationProperties

// application.yml
payment:
  gateway-url: https://api.stripe.com/v1
  api-key: sk_live_xxxx
  timeout-seconds: 30
  retry:
    max-attempts: 3
    back-off-ms: 500

// 1. Define the POJO
@ConfigurationProperties(prefix = "payment")
@Validated   // enables JSR-303 validation on fields
public class PaymentProperties {

    @NotBlank
    private String gatewayUrl;

    @NotBlank
    private String apiKey;

    @Min(1) @Max(120)
    private int timeoutSeconds;

    private Retry retry = new Retry();  // nested object

    // getters + setters (or use a record in Boot 3.x)

    public static class Retry {
        private int maxAttempts = 3;
        private long backOffMs = 500;
        // getters + setters
    }
}

// 2. Register (choose one approach)
@SpringBootApplication
@ConfigurationPropertiesScan   // scans for all @ConfigurationProperties in package
public class App { }

// 3. Inject anywhere
@Service
@RequiredArgsConstructor
public class PaymentService {
    private final PaymentProperties props;
    // props.getGatewayUrl(), props.getRetry().getMaxAttempts(), etc.
}

// Spring Boot 3+ — immutable record binding
@ConfigurationProperties(prefix = "payment")
public record PaymentProperties(
    @NotBlank String gatewayUrl,
    @NotBlank String apiKey,
    @Min(1) int timeoutSeconds
) {}

// All of these bind to the same field (relaxed binding):
# application.properties
payment.gateway-url=...     # kebab-case  ✅
payment.gatewayUrl=...      # camelCase   ✅
PAYMENT_GATEWAY_URL=...     # env var     ✅ (Kubernetes ConfigMap / Secret)

<!-- Maven: generates META-INF/spring-configuration-metadata.json -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

// Gradle
annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'

// After adding this, IntelliJ / VS Code will show:
// - property key suggestions in application.yml
// - type hints (int, String, Duration)
// - Javadoc from the field's comment as description