Segue um exemplo prático que mostre como um diagrama UML de sequência pode se transformar em uma especificação OpenAPI dentro de um fluxo Spec-Driven Development, considerando o cenário de um sistema de gerenciamento de estacionamento.
1. Cenário
Queremos descrever o processo em que um motorista chega ao estacionamento, um ticket é emitido, e o sistema registra a entrada.
Atores e componentes envolvidos:
- Motorista (usuário do aplicativo ou do terminal)
- AppEstacionamento (cliente — app móvel)
- API Estacionamento (servidor)
- Banco de Dados
2. Diagrama UML de sequência (conceitual)
O motorista informa sua placa no aplicativo. O app envia uma requisição HTTP POST /entradas para a API. A API cria um novo registro no banco de dados e retorna um ticket_id que será usado para controle da estadia.
3. Tradução da UML para uma especificação OpenAPI (Spec-Driven)
Agora, essa sequência se transforma em uma especificação OpenAPI, que servirá de contrato entre o front-end e o back-end.
4. Como isso se encaixa no Spec-Driven Development
Aqui está o ponto-chave: essa especificação não é só um documento, mas o ponto central do desenvolvimento.
A partir dela, ferramentas como Swagger Codegen, OpenAPI Generator, ou IDEs como a Kiro podem:
- Gerar automaticamente os controladores da API no backend (em Python, Java, Node, etc.);
- Criar stubs e mocks para o front-end testar o fluxo sem o backend pronto;
- Validar se o código implementa o contrato;
- Atualizar a documentação interativa automaticamente (Swagger UI).
Assim, o time desenvolve a partir da especificação gerada do modelo UML, garantindo que o comportamento modelado visualmente é o mesmo comportamento implementado no código.
5. Visão integrada
Podemos pensar no fluxo assim:
Essa integração elimina ambiguidades, acelera o desenvolvimento e assegura que a documentação, o modelo e o código estejam sempre alinhados.
6. Conclusão
Neste exemplo, o diagrama UML de sequência atua como o ponto de partida conceitual — descrevendo o que deve acontecer. A especificação OpenAPI formaliza isso em um documento legível por máquina, que guia a geração automática de código e validações.
Assim, a UML e o Spec-Driven Development coexistem harmoniosamente:
A UML comunica, o OpenAPI formaliza, e o Spec-Driven executa.