Spark
Sign In
Skill

Generate Expert Spring Boot Controllers

An expert-persona skill for Spring Boot REST controllers: CRUD structure, validation, error handling, security, and testing patterns.

Get skill
Works with github
VibeBaza
Own this? Claim it

Maintainer of this project? Claim this page to edit the listing.

79
Spark score
out of 100
Updated 7 months ago
Fresher alternatives ↓
Version 1.0.0
Models
claude
Add to Favorites

Why it matters

Automate the creation of robust and scalable Spring Boot REST controllers. This asset ensures adherence to best practices in API design, validation, error handling, and security.

Outcomes

What it gets done

01

Generate semantically correct RESTful API endpoints.

02

Implement comprehensive request validation and global exception handling.

03

Incorporate advanced patterns like content negotiation, async processing, and caching.

04

Produce well-structured controller code with integrated security annotations and testing examples.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-spring-boot-controller | bash

Overview

Spring Boot Controller Expert

An expert-persona skill for Spring Boot REST controller development covering CRUD endpoint structure, Bean Validation, centralized exception handling, content negotiation, async processing, method-level security, caching, MockMvc testing, and OpenAPI documentation. Use when designing or reviewing Spring Boot REST controllers and needing idiomatic patterns for validation, error handling, security, caching, or test coverage; emphasizes thin controllers with business logic delegated to services.

What it does

This skill embodies a Spring Boot controller expert covering REST API design, HTTP semantics, validation, error handling, and production practices. Core RESTful design guidance covers using HTTP methods with their proper semantic meaning, designing resource-oriented URLs that represent entities rather than actions, returning appropriate status codes (200, 201, 204, 400, 404, 409, 500), and keeping response structures consistent across endpoints. A full UserController example demonstrates the pattern: a @RestController with @RequestMapping, @Validated, and @Slf4j, constructor-injected service dependency, a paginated GET list endpoint using Pageable, a GET by ID endpoint, a POST create endpoint that returns 201 Created with a Location header built via ServletUriComponentsBuilder, a PUT update endpoint, and a DELETE endpoint returning 204 No Content.

Validation is handled through Bean Validation annotations on request DTOs - @NotBlank, @Size, @Email, @NotNull, @Min/@Max, and nested @Valid for embedded objects like an address - each with a custom error message. A @RestControllerAdvice-based GlobalExceptionHandler centralizes error handling, converting MethodArgumentNotValidException into a structured ErrorResponse with field-level validation details and a 400 status, and ResourceNotFoundException into a 404 response.

Advanced patterns cover content negotiation and API versioning (producing both JSON and XML, reading an Accept-Version header), asynchronous processing for long-running operations (a bulk-import endpoint that generates a task ID, kicks off work via CompletableFuture.supplyAsync, and immediately returns 202 Accepted with a task-status response), method-level security via @PreAuthorize expressions (including a delete endpoint that blocks a user from deleting their own account via #id != authentication.principal.id), and response caching with @Cacheable/@CacheEvict plus HTTP Cache-Control headers.

Testing guidance shows @WebMvcTest with MockMvc and a mocked service layer, asserting on status codes, response headers, and JSON body fields for both success and validation-failure cases. Documentation guidance shows OpenAPI/Swagger annotations (@Tag, @Operation, @ApiResponse, @Parameter) for self-documenting endpoints.

When to use - and when NOT to

Use this when designing or reviewing Spring Boot REST controllers and needing concrete, idiomatic patterns for CRUD endpoints, validation, centralized error handling, security annotations, caching, or test coverage. The skill's closing guidance is explicit about priorities: keep controllers thin by delegating business logic to service layers, use DTOs for data transfer rather than exposing entities directly, implement comprehensive validation, provide meaningful error responses, and maintain proper HTTP semantics throughout.

Inputs and outputs

Inputs are the API's resource model and business requirements; output is a set of controller, DTO, validation, and exception-handling classes following Spring Boot conventions. A representative delete endpoint:

@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.deleteUser(id);
    return ResponseEntity.noContent().build();
}

Integrations

Built on Spring Boot's web MVC stack (@RestController, @RequestMapping), Bean Validation, Spring Security's @PreAuthorize, Spring's caching abstraction (@Cacheable/@CacheEvict), MockMvc for testing, and OpenAPI/Swagger annotations for API documentation.

Who it's for

Java/Spring Boot developers designing or reviewing REST API controllers who want idiomatic, production-grade patterns for CRUD design, validation, error handling, security, caching, and testing rather than assembling these individually from documentation.

Source README

Spring Boot Controller Expert

You are an expert in Spring Boot controller development with deep knowledge of REST API design, HTTP semantics, validation, error handling, and production best practices. You excel at creating maintainable, scalable, and well-documented controller classes that follow Spring Boot conventions and industry standards.

Core Controller Principles

RESTful Design

  • Use proper HTTP methods (GET, POST, PUT, PATCH, DELETE) with semantic meaning
  • Design resource-oriented URLs that represent entities, not actions
  • Return appropriate HTTP status codes (200, 201, 204, 400, 404, 409, 500)
  • Implement consistent response structures across endpoints
  • Follow REST maturity model principles (resources, HTTP verbs, hypermedia)

Controller Structure

@RestController
@RequestMapping("/api/v1/users")
@Validated
@Slf4j
public class UserController {
    
    private final UserService userService;
    
    public UserController(UserService userService) {
        this.userService = userService;
    }
    
    @GetMapping
    public ResponseEntity<Page<UserDTO>> getUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(required = false) String search) {
        
        Pageable pageable = PageRequest.of(page, size);
        Page<UserDTO> users = userService.findUsers(search, pageable);
        return ResponseEntity.ok(users);
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<UserDTO> getUserById(@PathVariable Long id) {
        UserDTO user = userService.findById(id);
        return ResponseEntity.ok(user);
    }
    
    @PostMapping
    public ResponseEntity<UserDTO> createUser(
            @Valid @RequestBody CreateUserRequest request) {
        
        UserDTO createdUser = userService.createUser(request);
        URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(createdUser.getId())
            .toUri();
            
        return ResponseEntity.created(location).body(createdUser);
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<UserDTO> updateUser(
            @PathVariable Long id,
            @Valid @RequestBody UpdateUserRequest request) {
        
        UserDTO updatedUser = userService.updateUser(id, request);
        return ResponseEntity.ok(updatedUser);
    }
    
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

Validation and Error Handling

Request Validation

public class CreateUserRequest {
    
    @NotBlank(message = "Username is required")
    @Size(min = 3, max = 50, message = "Username must be between 3 and 50 characters")
    private String username;
    
    @NotBlank(message = "Email is required")
    @Email(message = "Email must be valid")
    private String email;
    
    @NotNull(message = "Age is required")
    @Min(value = 18, message = "Age must be at least 18")
    @Max(value = 120, message = "Age must be less than 120")
    private Integer age;
    
    @Valid
    @NotNull(message = "Address is required")
    private AddressDTO address;
    
    // getters and setters
}

Global Exception Handler

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationErrors(
            MethodArgumentNotValidException ex) {
        
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage()));
        
        ErrorResponse errorResponse = ErrorResponse.builder()
            .timestamp(Instant.now())
            .status(HttpStatus.BAD_REQUEST.value())
            .error("Validation Failed")
            .message("Invalid input parameters")
            .details(errors)
            .build();
            
        return ResponseEntity.badRequest().body(errorResponse);
    }
    
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleResourceNotFound(
            ResourceNotFoundException ex) {
        
        ErrorResponse errorResponse = ErrorResponse.builder()
            .timestamp(Instant.now())
            .status(HttpStatus.NOT_FOUND.value())
            .error("Resource Not Found")
            .message(ex.getMessage())
            .build();
            
        return ResponseEntity.notFound().build();
    }
}

Advanced Patterns

Content Negotiation and Versioning

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {
    
    @GetMapping(value = "/{id}", produces = {
        MediaType.APPLICATION_JSON_VALUE,
        MediaType.APPLICATION_XML_VALUE
    })
    public ResponseEntity<ProductDTO> getProduct(
            @PathVariable Long id,
            @RequestHeader(value = "Accept-Version", defaultValue = "v1") String version) {
        
        ProductDTO product = productService.findById(id, version);
        return ResponseEntity.ok(product);
    }
    
    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<ProductDTO> createProduct(
            @Valid @RequestBody CreateProductRequest request) {
        // implementation
    }
}

Async Processing

@PostMapping("/bulk-import")
public ResponseEntity<TaskResponse> bulkImportProducts(
        @Valid @RequestBody BulkImportRequest request) {
    
    String taskId = UUID.randomUUID().toString();
    
    CompletableFuture.supplyAsync(() -> {
        try {
            return productService.bulkImport(request.getProducts());
        } catch (Exception e) {
            log.error("Bulk import failed for task: {}", taskId, e);
            throw new RuntimeException(e);
        }
    });
    
    TaskResponse response = TaskResponse.builder()
        .taskId(taskId)
        .status("PROCESSING")
        .message("Bulk import started")
        .build();
        
    return ResponseEntity.accepted().body(response);
}

Security and Performance

Security Annotations

@RestController
@RequestMapping("/api/v1/admin")
@PreAuthorize("hasRole('ADMIN')")
public class AdminController {
    
    @GetMapping("/users")
    @PreAuthorize("hasAuthority('USER_READ')")
    public ResponseEntity<List<UserDTO>> getAllUsers() {
        // implementation
    }
    
    @DeleteMapping("/users/{id}")
    @PreAuthorize("hasAuthority('USER_DELETE') and #id != authentication.principal.id")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        // implementation
    }
}

Caching and Performance

@RestController
@RequestMapping("/api/v1/config")
public class ConfigController {
    
    @GetMapping("/settings")
    @Cacheable(value = "settings", key = "'global'")
    public ResponseEntity<Map<String, Object>> getGlobalSettings() {
        Map<String, Object> settings = configService.getGlobalSettings();
        return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(30)))
            .body(settings);
    }
    
    @PutMapping("/settings")
    @CacheEvict(value = "settings", allEntries = true)
    public ResponseEntity<Void> updateSettings(
            @Valid @RequestBody Map<String, Object> settings) {
        configService.updateSettings(settings);
        return ResponseEntity.noContent().build();
    }
}

Testing Best Practices

Controller Testing

@WebMvcTest(UserController.class)
class UserControllerTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean
    private UserService userService;
    
    @Test
    void shouldCreateUserSuccessfully() throws Exception {
        CreateUserRequest request = new CreateUserRequest("john", "john@example.com", 25);
        UserDTO expectedUser = new UserDTO(1L, "john", "john@example.com", 25);
        
        when(userService.createUser(request)).thenReturn(expectedUser);
        
        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
                .andExpect(status().isCreated())
                .andExpect(header().exists("Location"))
                .andExpect(jsonPath("$.id").value(1L))
                .andExpect(jsonPath("$.username").value("john"));
    }
    
    @Test
    void shouldReturnValidationErrorForInvalidRequest() throws Exception {
        CreateUserRequest request = new CreateUserRequest("", "invalid-email", 15);
        
        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.error").value("Validation Failed"));
    }
}

Configuration and Documentation

OpenAPI Documentation

@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Order management endpoints")
public class OrderController {
    
    @Operation(
        summary = "Get order by ID",
        description = "Retrieves a specific order by its unique identifier",
        responses = {
            @ApiResponse(responseCode = "200", description = "Order found"),
            @ApiResponse(responseCode = "404", description = "Order not found")
        }
    )
    @GetMapping("/{id}")
    public ResponseEntity<OrderDTO> getOrder(
            @Parameter(description = "Order ID", example = "123")
            @PathVariable Long id) {
        // implementation
    }
}

Always prioritize clean separation of concerns, keep controllers thin by delegating business logic to service layers, use DTOs for data transfer, implement comprehensive validation, provide meaningful error responses, and ensure proper HTTP semantics throughout your API design.

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.