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/good-delegate-impl.java

View on GitHub
// GOOD — implements generated delegate, never modifies generated code, maps between models

@Service
@RequiredArgsConstructor
public class OrderApiDelegateImpl implements OrdersApiDelegate {

    private final OrderService orderService;

    @Override
    public ResponseEntity<OrderDto> getOrderById(UUID id) {
        Order order = orderService.findById(id);
        return ResponseEntity.ok(toDto(order));
    }

    @Override
    public ResponseEntity<OrderDto> createOrder(CreateOrderRequestDto request) {
        Order order = orderService.createOrder(
            request.getCustomerEmail(),
            request.getItems().stream()
                .map(i -> new OrderItemCommand(i.getProductId(), i.getQuantity()))
                .toList());
        return ResponseEntity.status(HttpStatus.CREATED).body(toDto(order));
    }

    @Override
    public ResponseEntity<PageOrderDto> listOrders(Integer page, Integer size) {
        Page<Order> orders = orderService.findAll(PageRequest.of(page, size));
        PageOrderDto dto = new PageOrderDto()
            .content(orders.getContent().stream().map(this::toDto).toList())
            .totalElements(orders.getTotalElements())
            .totalPages(orders.getTotalPages());
        return ResponseEntity.ok(dto);
    }

    // Map domain → generated DTO (never expose domain model via API)
    private OrderDto toDto(Order order) {
        return new OrderDto()
            .id(order.getId())
            .status(OrderDto.StatusEnum.fromValue(order.getStatus().name()))
            .customerEmail(order.getCustomerEmail())
            .createdAt(order.getCreatedAt());
    }
}
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