Spec-First: Inverta o seu fluxo de desenvolvimento

O Ciclo Vicioso do "Code-First"

No desenvolvimento tradicional de APIs (conhecido como Code-First), o fluxo de trabalho costuma ser assim:

1. O desenvolvedor Backend cria as entidades, os controllers e a lógica de negócios no Spring Boot.

2. O código entra em ambiente de testes.

3. O desenvolvedor Frontend tenta consumir o endpoint e descobre que o campo dataNascimento que ele esperava na verdade foi mapeado no Java como birthDate.

4. O Frontend pede a alteração, o Backend altera, gera um novo deploy e reinicia o ciclo.

Esse desalinhamento gera fricção entre as equipes e desperdiça um tempo precioso. Para piorar, a documentação (como o Swagger UI) muitas vezes se torna uma "ferramenta de consulta": ela apenas reflete o que o código faz hoje, e qualquer alteração no backend quebra o frontend sem aviso prévio.

O que é a abordagem Spec-First?

O Spec-First inverte essa ordem. Em vez de o código ditar como a documentação deve ser, a especificação dita como o código deve ser escrito.

Antes de abrir a IDE para programar o backend ou o frontend, as duas equipes se reúnem e escrevem o contrato da API usando o padrão OpenAPI Specification (OAS), geralmente em um arquivo YAML limpo.

Esse arquivo YAML se torna a única fonte da verdade (Single Source of Truth). Ele descreve quais são as rotas, quais parâmetros de URL são aceitos, quais campos o JSON de envio deve ter e quais serão os códigos de status HTTP de retorno.

Spec-First na Prática: Do YAML ao Código Java Automatizado

A maior beleza do Spec-First não é apenas o alinhamento conceitual, mas a automação. Se você tem uma especificação OpenAPI bem escrita, você não precisa gastar tempo escrevendo interfaces de Controllers ou DTOs na mão. Ferramentas como o OpenAPI Generator fazem isso por você.

Imagine o seguinte trecho da especificação (api-spec.yml) que define o cadastro de um produto:

openapi: 3.0.3
info:
  title: API de Produtos
  version: 1.0.0
paths:
  /produtos:
    post:
      summary: Cria um novo produto
      operationId: criarProduto
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProdutoDTO'
      responses:
        '21':
          description: Produto criado com sucesso

Em vez de criar a classe ProdutoDTO e o ProdutoController manualmente no Spring Boot, nós adicionamos o plugin do OpenAPI Generator no nosso pom.xml do Maven.

Quando rodamos o comando (mvn clean compile), o plugin lê esse arquivo YAML e gera automaticamente todas as interfaces dos controllers, as anotações do Spring (@PostMapping, @RequestBody), as validações do Bean Validation (@NotNull, @Size) e os DTOs Java dentro da pasta target/generated-sources.

Tudo o que o desenvolvedor Back-end precisa fazer é implementar a interface gerada:

@RestController
public class ProdutoControllerImpl implements ProdutosApi {

    private final ProdutoService service;

    public ProdutoControllerImpl(ProdutoService service) {
        this.service = service;
    }

    @Override
    public ResponseEntity<ProdutoResponseDTO> criarProduto(ProdutoDTO produtoDTO) {
        // A assinatura do método e o DTO vieram prontos da especificação!
        var resposta = service.salvar(produtoDTO);
        return ResponseEntity.status(HttpStatus.CREATED).body(resposta);
    }
}

Por que o Spec-First acelera o seu desenvolvimento?

1. Desenvolvimento Paralelo Real: Assim que o arquivo de especificação YAML é aprovado, o time de backend pode começar a codificar a lógica de negócios no Java, enquanto o time de frontend usa o próprio arquivo YAML para gerar um Mock Server (servidor simulado). O frontend consegue construir todas as telas e integrações sem precisar esperar o backend terminar o deploy.

2. Garantia de Contrato (Contract Testing): Se o backend alterar o nome de um campo no código e isso violar o que foi definido na especificação, o projeto não compila. O erro é pego imediatamente em tempo de compilação ou na esteira de CI/CD, antes de quebrar o ambiente de homologação.

3. Documentação Sempre Atualizada: Como o código nasce a partir da especificação, é impossível a sua documentação do Swagger estar desatualizada em relação ao que a API realmente faz em produção.

Conclusão

Adotar o Spec-First exige uma mudança de cultura. No início, resistir à tentação de sair digitando código no Spring Boot parece difícil, e gastar tempo desenhando rotas em um arquivo YAML pode parecer burocracia.

No entanto, para quem gerencia ecossistemas de microsserviços, essa metodologia é a estratégia mais eficiente para reduzir o retrabalho e garantir que o seu software seja integrado sem surpresas desagradáveis na hora do deploy.