Skip to content

rrezartprebreza/spring-boot-skills / skills/spring-boot-3/openapi-first

openapi-first

Verified

Use when the project follows API-first / OpenAPI-first approach: generating controller interfaces, DTOs, and clients from an OpenAPI spec. Use when you see openapi.yaml, openapi-generator-maven-plugin, or ApiDelegate pattern in the project.

examples/bad-delegate-impl.java

View on GitHub
// BAD — modifies generated controller, mixes models, wrong config

// Editing the GENERATED controller directly — will be overwritten on next build!
@RestController
@RequestMapping("/api/v1/orders")
public class OrdersApiController {         // this file is generated — don't touch it

    @Autowired                             // field injection
    private OrderRepository orderRepository;

    @GetMapping("/{id}")
    public Order getOrder(@PathVariable Long id) {    // Long ID instead of UUID
        return orderRepository.findById(id)
            .orElseThrow();                           // returns domain entity, not generated DTO
    }

    @PostMapping
    public ResponseEntity<OrderDto> createOrder(@RequestBody OrderDto dto) {
        // Using generated DTO as both request AND response — spec has separate schemas
        Order order = new Order();
        order.setEmail(dto.getCustomerEmail());
        order.setStatus(dto.getStatus().name());      // mixes generated enum with domain
        orderRepository.save(order);
        return ResponseEntity.ok(dto);                // returns input DTO, not persisted state
    }
}

// Plugin config missing useSpringBoot3=true:
// <configOptions>
//     <useJakartaEe>false</useJakartaEe>              <!-- generates javax.* imports on Spring Boot 3 -->
//     <delegatePattern>false</delegatePattern>         <!-- no delegate — must edit generated code -->
// </configOptions>

// Generated sources committed to git — should be in .gitignore and target/
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall