Levando o diagrama de sequência da UML para o Spec-Driven Development – explicação em um sistema de estacionamento

Por

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.

openapi: 3.1.0
info:
  title: API do Estacionamento
  version: 1.0.0
  description: >
    Esta API gerencia as entradas, saídas e pagamentos de veículos no estacionamento.
paths:
  /entradas:
    post:
      summary: Registra a entrada de um veículo no estacionamento
      description: >
        Cria um novo ticket de estacionamento para um veículo identificado pela placa.
      operationId: registrarEntrada
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                placa:
                  type: string
                  example: ABC1D23
              required:
                - placa
      responses:
        "201":
          description: Ticket criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket_id:
                    type: string
                    example: TCK-20251021-001
        "400":
          description: Dados inválidos ou placa ausente
Code language: YAML (yaml)

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:

UML (modelagem visual)
       ↓
Spec (OpenAPI ou JSON Schema)
       ↓
Código gerado automaticamente
       ↓
Documentação e testes sincronizados
Code language: SCSS (scss)

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.

Deixe um comentário