Spring Web MVC

@RestController
@RequestMapping("/api/v1/orders")
class OrderController {
  private final OrderService orderService;

  OrderController(OrderService orderService) {
    this.orderService = orderService;
  }

  @GetMapping("/{id}")
  OrderDto get(@PathVariable long id) {
    return orderService.findDto(id);
  }
}

@PostMapping(
    path = "/{id}/documents",
    consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
    produces = MediaType.APPLICATION_JSON_VALUE
)
DocumentDto upload(
    @PathVariable long id,
    @RequestPart("file") MultipartFile file
) {
  return documentService.store(id, file);
}

@GetMapping("/search")
Page<OrderDto> search(
    @RequestParam(required = false) String q,
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "20") int size,
    @RequestHeader(value = "X-Tenant-Id", required = false) String tenantId,
    Pageable pageable  // overrides page/size if present
) {
  return orderService.search(q, tenantId, pageable);
}

@PostMapping
ResponseEntity<OrderDto> create(@Valid @RequestBody CreateOrderRequest request) {
  OrderDto created = orderService.create(request);
  URI location = URI.create("/api/v1/orders/" + created.id());
  return ResponseEntity.created(location).body(created);
}

@GetMapping("/{id}")
ResponseEntity<OrderDto> get(@PathVariable long id) {
  return orderService.findDto(id)
      .map(ResponseEntity::ok)
      .orElse(ResponseEntity.notFound().build());
}

public record CreateOrderRequest(
    @NotBlank @Size(max = 64) String customerId,
    @NotEmpty @Size(max = 50) List<@NotNull @Positive Long> productIds,
    @Email String contactEmail,
    @Pattern(regexp = "STANDARD|EXPRESS") String shippingTier,
    @Min(1) @Max(100) int quantity
) {}

@PostMapping
@ResponseStatus(HttpStatus.CREATED)
OrderDto create(@Valid @RequestBody CreateOrderRequest request) {
  return orderService.create(request);
}

public interface OnCreate {}
public interface OnUpdate {}

public record UserRequest(
    @Null(groups = OnCreate.class)
    @NotNull(groups = OnUpdate.class)
    Long id,
    @NotBlank(groups = {OnCreate.class, OnUpdate.class})
    String name
) {}

@PostMapping
UserDto create(@Validated(OnCreate.class) @RequestBody UserRequest req) { /* ... */ }

@PutMapping("/{id}")
UserDto update(@Validated(OnUpdate.class) @RequestBody UserRequest req) { /* ... */ }

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = DateRangeValidator.class)
public @interface ValidDateRange {
  String message() default "endDate must be after startDate";
  Class<?>[] groups() default {};
  Class<? extends Payload>[] payload() default {};
}

class DateRangeValidator implements ConstraintValidator<ValidDateRange, BookingRequest> {
  @Override
  public boolean isValid(BookingRequest value, ConstraintValidatorContext ctx) {
    if (value == null) return true;
    return value.endDate().isAfter(value.startDate());
  }
}

@RestController
@RequestMapping("/api/orders")
class OrderController {
  @GetMapping("/{id}")
  OrderDto get(@PathVariable long id) {
    return orderService.findDto(id);
  }

  @ExceptionHandler(OrderNotFoundException.class)
  @ResponseStatus(HttpStatus.NOT_FOUND)
  ProblemDetail notFound(OrderNotFoundException ex) {
    return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
  }
}

@RestControllerAdvice
class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

  @ExceptionHandler(BusinessRuleException.class)
  ResponseEntity<ProblemDetail> business(BusinessRuleException ex) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(
        HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
    problem.setProperty("errorCode", ex.getCode());
    return ResponseEntity.unprocessableEntity().body(problem);
  }

  @Override
  protected ResponseEntity<Object> handleMethodArgumentNotValid(
      MethodArgumentNotValidException ex,
      HttpHeaders headers,
      HttpStatusCode status,
      WebRequest request
  ) {
    List<String> errors = ex.getBindingResult().getFieldErrors().stream()
        .map(fe -> fe.getField() + ": " + fe.getDefaultMessage())
        .toList();
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(status, "Validation failed");
    problem.setProperty("errors", errors);
    return ResponseEntity.badRequest().body(problem);
  }
}

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Order 42 not found",
  "instance": "/api/v1/orders/42"
}

public record OrderDto(
    long id,
    @JsonProperty("customer_id") String customerId,
    @JsonIgnore String internalNotes,
    @JsonInclude(JsonInclude.Include.NON_NULL) BigDecimal discount,
    @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ssXXX")
    Instant createdAt
) {}

spring:
  jackson:
    default-property-inclusion: non_null
    serialization:
      write-dates-as-timestamps: false
      indent-output: true
    deserialization:
      fail-on-unknown-properties: false
    property-naming-strategy: SNAKE_CASE

public class MoneySerializer extends JsonSerializer<Money> {
  @Override
  public void serialize(Money value, JsonGenerator gen, SerializerProvider serializers)
      throws IOException {
    gen.writeStartObject();
    gen.writeNumberField("amount", value.amount());
    gen.writeStringField("currency", value.currency().getCurrencyCode());
    gen.writeEndObject();
  }
}

@JsonSerialize(using = MoneySerializer.class)
public record Money(BigDecimal amount, Currency currency) {}

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
class RequestIdFilter extends OncePerRequestFilter {
  @Override
  protected void doFilterInternal(
      HttpServletRequest request,
      HttpServletResponse response,
      FilterChain chain
  ) throws ServletException, IOException {
    String requestId = Optional.ofNullable(request.getHeader("X-Request-Id"))
        .orElse(UUID.randomUUID().toString());
    MDC.put("requestId", requestId);
    response.setHeader("X-Request-Id", requestId);
    try {
      chain.doFilter(request, response);
    } finally {
      MDC.remove("requestId");
    }
  }
}

@Bean
FilterRegistrationBean<RequestIdFilter> requestIdFilter(RequestIdFilter filter) {
  FilterRegistrationBean<RequestIdFilter> bean = new FilterRegistrationBean<>(filter);
  bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
  bean.addUrlPatterns("/api/*");
  return bean;
}

@Component
class TimingInterceptor implements HandlerInterceptor {
  private static final String START = "timing.start";

  @Override
  public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
    req.setAttribute(START, System.nanoTime());
    return true;
  }

  @Override
  public void afterCompletion(HttpServletRequest req, HttpServletResponse res,
      Object handler, Exception ex) {
    long start = (long) req.getAttribute(START);
    long ms = (System.nanoTime() - start) / 1_000_000;
    log.info("{} {} {}ms", req.getMethod(), req.getRequestURI(), ms);
  }
}

@Configuration
class WebMvcConfig implements WebMvcConfigurer {
  private final TimingInterceptor timingInterceptor;

  WebMvcConfig(TimingInterceptor timingInterceptor) {
    this.timingInterceptor = timingInterceptor;
  }

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(timingInterceptor).addPathPatterns("/api/**");
  }
}

@Configuration
class StaticResourceConfig implements WebMvcConfigurer {
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/docs/**")
        .addResourceLocations("classpath:/docs/")
        .setCacheControl(CacheControl.maxAge(1, TimeUnit.HOURS).cachePublic());
  }
}

@Configuration
class CorsConfig implements WebMvcConfigurer {
  @Override
  public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/api/**")
        .allowedOrigins("https://app.acme.com", "http://localhost:3000")
        .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
        .allowedHeaders("*")
        .exposedHeaders("X-Request-Id")
        .allowCredentials(true)
        .maxAge(3600);
  }
}

@CrossOrigin(origins = "https://app.acme.com", maxAge = 3600)
@RestController
@RequestMapping("/api/public")
class PublicApiController {}