Draw.io + PlantUML - Como tornar mais fácil o processo de documentação

Nota pessoal: A trilha sonora que ouvi enquanto escrevia esse artigo.
https://open.spotify.com/playlist/0n81ha8dSdYLDVc8VpCPsd?si=70347c8542f44a84

Fala pessoal, a documentação é uma parte fundamental de todo projeto de desenvolvimento, embora nem sempre seja fácil ou divertida.

Recentemente, descobri que o draw.io possui uma integração com o plantUML, que pode ser muito útil na criação de Diagramas UML.

Por isso, resolvi escrever esse artigo para começar uma série sobre como facilitar a documentação de projetos.

Mas antes de continuar, vamos dar alguns passos para trás e entender um pouco mais sobre o que é UML.

A UML (do inglês Unified Modeling Language) é a Linguagem de Modelagem Unificada, é uma linguagem-padrão para a elaboração da estrutura de projetos de software.

É adequada para a modelagem de sistemas, incluindo sistemas corporativos, aplicações baseadas na web e sistemas complexos embutidos em tempo real.

A UML é uma linguagem expressiva que cobre todas as visões necessárias ao desenvolvimento e implantação de sistemas de software complexos.

Em resumo, UML é um padrão de escrita para criar diagramas, que tem como objetivo ajudar na documentação e no entendimento das regras de negócio de um projeto no futuro.

É importante notar que um modelo UML e um diagrama UML são coisas diferentes, o segundo é uma representação gráfica do primeiro.

Eu adoro ver coisas representadas visualmente, é mais fácil entender um processo ou regra de negócio na minha opinião, quanto mais claro, menos complicado será a hora de colocarmos a ideia em prática.

Mas conceitos a parte vamos para a parte mais prática.

Na animação abaixo eu mostro um exemplo bem simples de criação de "fluxo" de autenticação no draw.io, onde o usuário faz o login e logo em seguida ele mostra a tela de boas vindas.

Como nós podemos representar esse fluxo utilizando um diagrama de sequencia?

Nota: O diagrama de sequência é uma ferramenta visual que mostra como diferentes componentes de um sistema se relacionam e comunicam entre si ao longo do tempo. Ele ajuda a entender o fluxo de mensagens entre objetos ou componentes, mostrando quem envia a mensagem, quem a recebe e em que ordem isso acontece. É uma forma simples de ilustrar a ordem de eventos em um processo, e pode ser útil para esclarecer dúvidas sobre a lógica de um sistema ou de um negócio. É como um mapa mental que ajuda a visualizar o funcionamento de algo e a identificar pontos onde pode haver melhorias. Em resumo, o diagrama de sequência é uma ferramenta eficaz para ajudar a compreender o funcionamento de um sistema de maneira visual e fácil de entender.

A imagem abaixo representa como seria esse mesmo fluxo porém em um diagrama de Sequencia perceba que ele é mais detalhado mostrando como que o sistema deve se comportar para que o login do usuário aconteça apesar de ser um diagrama de sequencia ainda é superficial pois nesse caso não informamos quais as informações que devem ser encaminhadas de um ponto ao outro.

Agora na imagem abaixo vemos esse mesmo diagrama, porém um pouco mais especificado onde nós conseguimos saber quais os métodos que serão executados em cada momento e quais informações eles devem passar

Por exemplo observando a imagem a cima, eu sei que caso no passo 6 não retorne um usuário ( User === null ) ele deve acusar um erro e com isso chamar o metodo HTTPResponse que irá encaminhar uma resposta com código 401, e a mensagem "credencial inválida" para a tela de login.

Perceba que dessa forma a pessoa que for realizar o desenvolvimento desse fluxo consegue de forma clara saber o que está acontecendo.

Nota pessoal: Eu particularmente não gosto de chegar nesse nível de detalhamento, pois na 'vida real' o código é vivo e se altera muito, então acaba tornado obsoleto esse nível de detalhamento muito rápido, e o trade-off começa a ficar caro para manter atualizado a documentação.

Pois bem, depois dessa breve explicação da idéia de diagrama de sequência, vamos voltar ao draw.io e como nós podemos construir diagramas de forma simples e rápida nele.

Para isso iremos usar o PlantUML

Nota: O PlantUML é uma ferramenta de geração de diagramas UML (Unified Modeling Language) baseada em texto. É uma forma simples e fácil de representar diagramas UML usando uma sintaxe de marcação simples, e permite a geração automática de diagramas a partir do código. Além de suportar diagramas de classes, sequência, casos de uso, estados, objetos e componentes, PlantUML também suporta vários outros diagramas técnicos e de negócios, tornando-se uma ferramenta versátil e útil para modelagem de sistemas e processos.

Para acessar o PlantUML dentro do draw.io siga os seguintes passos:

1. No menu superior vá na opção Arrange
2. Logo em seguida Insert
3. Depois Advanced
4. e por vim Clique em PlantUML

Ao fazer isso irá abrir uma janela com um exemplo de diagrama, clique em "Insert"

Feito isso será renderizado aquele exemplo de diagrama dentro do draw.io.

Para editar basta clicar duas vezes sobre a imagem e a janela para edição irá abrir novamente.

Coloque o trecho de código abaixo na janela de edição e clique em "Apply"

@startuml
autonumber

actor       Usuario        as User
boundary    Login          as Login
control     Servidor       as System
database    Banco_de_Dados as DB


User -> Login : document.ready()
Login -> Login : valida_login()

alt user.access_token !== null
    Login -[#green]x Login: redirect()
    note right: Redireciona o usuário para tela de login    
end

User -> Login: autenticar(email: string, senha: string)
Login -> System : usuario_controladora(email: string, senha: string): User
System -> DB: buscar_usuario(email: string, senha: string): User

alt User === null
    rnote over System #FFAAAA: Usuário não foi encontrado\ne deve retornar uma mensagem\nde erro para o usuário.
    DB -[#red]> System: new Error("Usuário não encontrado")
    System -[#red]x Login: HTTPResponse(401, "Credencial inválida")
else
    DB --[#green]> System:
    System -[#green]> Login: HTTPResponse(200, "Usuário lgoado com sucesso")
    note over Login: Usuário deve ser redirecionado para tela de Boas vindas
    Login -[#green]x Login: redirect()
end

@enduml

O resultado que você terá é o diagrama que foi mostrado ali em cima 😉

Nesse caso o PlantUML serve quase que como uma linguagem de marcação que facilita e MUITO criarmos diagramas com um custo de manutenção muito menor, afinal por ser uma "linguagem" conseguimos editar e utilizar sua sintaxe ao nosso favor.

Dica bonus:

Existem várias extensões que você pode usar no seu editor de código favorito que ajuda na hora de escrever as descrições no PlantUML como por exemplo para o VSCode encontrei esse aqui que permite você visualizar uma preview em tempo real enquanto você está escrevendo e caso queira também utilizar o Draw.io dentro do VSCode você pode utilizando esse plugin aqui

Material de apoio:
https://plantuml.com/sequence-diagram
https://plantuml.com/faq
https://en.wikipedia.org/wiki/PlantUML
https://pt.wikipedia.org/wiki/Diagrama_de_sequ%C3%AAncia
https://www.lucidchart.com/pages/pt/o-que-e-uml
https://pt.wikipedia.org/wiki/UML
https://abapinho.com/2017/09/plantuml-finalmente-o-uml-da-para-usar/