Como Criar Endpoints - ecosif-masterdata

Este guia explica como criar novos endpoints REST no ecosif-masterdata seguindo os padrões do projeto.

Estrutura Básica

1. Criar Controller

Crie uma nova classe Controller no pacote io.ecosif.masterdata.company.controller:

package io.ecosif.masterdata.company.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@Slf4j
@RestController
@RequestMapping("/api/exemplo")
@Tag(name = "Exemplo", description = "Endpoints de exemplo")
@SecurityRequirement(name = "bearer-jwt")
public class ExemploController {

    @GetMapping
    @Operation(summary = "Listar exemplos", description = "Retorna lista de exemplos")
    public ResponseEntity<?> listar() {
        log.info("Listando exemplos");
        // Implementação
        return ResponseEntity.ok().build();
    }
}

2. Criar DTO

Crie DTOs no pacote io.ecosif.masterdata.company.dto:

package io.ecosif.masterdata.company.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

import javax.validation.constraints.NotBlank;

@Data
@Schema(description = "DTO de exemplo")
public class ExemploDTO {

    @NotBlank(message = "Nome é obrigatório")
    @Schema(description = "Nome do exemplo", example = "Exemplo 1", required = true)
    private String nome;
}

3. Criar Service

Crie Services no pacote io.ecosif.masterdata.company.service:

package io.ecosif.masterdata.company.service;

import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Slf4j
@Service
@Transactional
public class ExemploService {

    public void processar(String nome) {
        log.info("Processando: {}", nome);
        // Lógica de negócio
    }
}

Padrões e Convenções

Validação

Valide DTOs usando Bean Validation:

@PostMapping
public ResponseEntity<?> criar(@Valid @RequestBody ExemploDTO dto) {
    // DTO já foi validado
}

Logging

Use @Slf4j para logging:

@Slf4j
@RestController
public class ExemploController {

    @PostMapping
    public ResponseEntity<?> criar(@Valid @RequestBody ExemploDTO dto) {
        log.info("Criando exemplo: {}", dto.getNome());
    }
}

Autenticação

Todos os endpoints são protegidos por padrão. O token JWT é validado automaticamente.

Para acessar o usuário autenticado:

@GetMapping
public ResponseEntity<?> listar(
    @AuthenticationPrincipal LocalUser localUser
) {
    // Usar informações do usuário
}

Exemplo Completo

Veja os controllers existentes como referência: - CompanyController - BranchController - ChartOfAccountsController

Recursos

• Guia de Contribuição