Skip to content
ContractShield

Java Quick Start

Get ContractShield protecting your Spring Boot API in under 5 minutes.

Installation

Maven

<dependency>
    <groupId>dev.contractshield</groupId>
    <artifactId>contractshield-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'dev.contractshield:contractshield-spring-boot-starter:1.0.0'

Spring Boot Setup

application.yml

contractshield:
  enabled: true
  contracts-dir: classpath:contracts/
  vulnerability-scan: true

Enable ContractShield

import dev.contractshield.spring.EnableContractShield;


@SpringBootApplication
@EnableContractShield
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Annotation-Based Validation

Use annotations to validate endpoints:

import dev.contractshield.spring.annotations.ValidateContract;
import dev.contractshield.spring.annotations.CELExpression;


@RestController
@RequestMapping("/api")
public class OrderController {


    @PostMapping("/orders")
    @ValidateContract(schema = "schemas/order.json")
    @CELExpression(
        value = "data.total > 0",
        message = "Total must be positive"
    )
    public ResponseEntity<OrderResponse> createOrder(
            @RequestBody OrderRequest request) {
        return ResponseEntity.ok(new OrderResponse("success"));
    }
}

Your First Contract

Create src/main/resources/contracts/orders.json:

{
  "endpoint": "/api/orders",
  "method": "POST",
  "schema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": { "type": "string" },
        "minItems": 1
      },
      "total": {
        "type": "number",
        "minimum": 0
      }
    },
    "required": ["items", "total"]
  },
  "invariants": [
    {
      "expr": "request.body.total >= 10.00",
      "message": "Minimum order value is $10"
    }
  ]
}

Filter-Based Validation

For global validation, use the ContractShield filter:

import dev.contractshield.spring.filter.ContractShieldFilter;


@Configuration
public class SecurityConfig {


    @Bean
    public FilterRegistrationBean<ContractShieldFilter> contractShieldFilter() {
        FilterRegistrationBean<ContractShieldFilter> registration =
            new FilterRegistrationBean<>();
        registration.setFilter(new ContractShieldFilter());
        registration.addUrlPatterns("/api/*");
        registration.setOrder(1);
        return registration;
    }
}

CEL Invariants

Add complex business logic with CEL:

@PostMapping("/transfer")
@CELExpression(
    value = "data.amount <= context.user.balance",
    message = "Insufficient balance"
)
@CELExpression(
    value = "data.amount > 0 && data.amount <= 10000",
    message = "Amount must be between 0 and 10000"
)
public ResponseEntity<TransferResponse> transfer(
        @RequestBody TransferRequest request) {
    return ResponseEntity.ok(new TransferResponse("success"));
}

Pro Features

Enable Pro features in application.yml:

contractshield:
  enabled: true
  license-key: ${CONTRACTSHIELD_LICENSE_KEY}
  learning-mode: true
  sink-protection: true


  # Actuator metrics endpoint
  metrics:
    enabled: true

Actuator Metrics

ContractShield exposes metrics via Spring Actuator:

management:
  endpoints:
    web:
      exposure:
        include: contractshield,health,metrics

Access metrics at /actuator/contractshield:

{
  "requests_validated": 15234,
  "requests_blocked": 42,
  "contracts_loaded": 12,
  "average_latency_ms": 0.3
}

Test It

Terminal window
# Valid request
curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"items": ["product-1"], "total": 25.00}'


# Invalid request (rejected)
curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"items": [], "total": 5.00}'

Next Steps