Draw.io + PlantUML - Como tornar mais fácil o processo de documentação
Tags: uml, kurybr, softwareenginner, plantuml
Published: 2023-02-01 12:11:15

---
title: Draw.io + PlantUML - Como tornar mais fácil o processo de documentação
published: true
description: Com esse artigo damos início a uma série de dicas de como podemos documentar nosso projeto de maneira descomplicada, falamos sobre o que é UML e Diagrama de sequência e trago uma dica de como utilizar duas plataformas para facilitar o nosso processo de documentação de diagramas o Draw.io e o plantUML.
tags: UML, kurybr, softwareenginner, plantUML
# cover_image: https://direct_url_to_image.jpg
---

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

||
|---|
|<small>Resumo: Nesse artigo, você vai entender um pouco sobre o que é UML, também o que é diagrama de sequencia e por fim veremos um exemplo de como utilizar a ferramenta plantUML junto com o Draw.io para facilitar nossas documentações</small>|



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](https://app.diagrams.net/) possui uma integração com o [plantUML](https://plantuml.com/), 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.

![Animação mostrando uma criação de fluxo simples](https://i.imgur.com/GBqgin9.gif)

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.

![Animação de um fluxo de diagrama de sequencia simples](https://i.imgur.com/BaQH1Bl.png)

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

![Animação de um fluxo de diagrama de sequencia complexo](https://i.imgur.com/jHhP8Zs.png)

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

![Figura representado os passos acima](https://i.imgur.com/TsuKT2B.gif)

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

![Figura representado os passos acima](https://i.imgur.com/IEYNYGj.gif)

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 😉 

![Animação de homem simbolizando a cabeça explodindo](https://media.tenor.com/Oc4nf8N08jIAAAAC/mind-blow-galaxy.gif)

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](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) 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](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio)  

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/