Criando e visualizando diagramas UML com IntelliJ
Nesta matéria vamos falar sobre como usar a IDE de desenvolvimento queridinha do mercado atualmente pelos devs Java, o IntelliJ IDEA, para criação e visualização de diagramas usando linguagem UML. Esta metodologia é interessante, pois permite que faça uma documentação de software bonita, rápida e padronizada, utilizando uma DSL simples. Além disso, pode fazer parte do código-fonte do seu projeto, facilitando sua evolução ao longo do ciclo de vida do software.
A documentação é uma importante parte na engenharia de software. Tão Amada quanto odiada, a documentação do software é a informação que descreve o produto para as pessoas envolvidas em seu desenvolvimento, implantação e uso. A documentação explica como o software opera ou como usá-lo e pode significar coisas diferentes para pessoas em funções diferentes. Além disso, é uma maneira de engenheiros e programadores descreverem formalmente seu produto e o processo que usaram para criá-lo. Ao longo do ciclo de vida de desenvolvimento de software, é muito provável que a documentação também tenha a necessidade de ser atualizada, e essa não é uma tarefa fácil, pois consome recursos e tempo. Lethbridge (2003), em seu artigo "How Software Engineers Use Documentation: The State of the Practice", discute que aproximadamente 44% dos engenheiros de softwares afirmam que a documentação está sempre desatualizada em relação ao estado atual de um sistema de software.
É muito comum o uso de documentação de sistemas para planejamento e aprovação de novos projetos. No entanto, é necessário um formato padronizado, como o UML, para que seja claro para qualquer interessado e facilite as discussões na equipe. Atualmente, faço parte da equipe de engenharia de software de um banco digital ao qual se faz necessário que as squads de desenvolvimento apresentem os projetos num fórum semanal para validação antes de iniciar o desenvolvimento. Para isso, é utilizado com muita frequência diagramas de sequência UML, que usaremos como exemplo nesta matéria.
Segundo Craig Larman (2001), no livro "Utilizando UML e Padrões", o Diagrama de Sequência (DS) é um artefato do sistema criado rápida e facilmente que ilustra os eventos de entrada e saída relacionados com o sistema em discussão. Deve ser feito um DS para a sequência principal e para cenários frequentes ou alternativas complexas.
Usaremos para criação e visualização de diagramas o PlantUML. Um componente para desenho de diagramas UML que usa código DSL como descrição de texto simples e legível por humanos. Esse método nos permite criar documentação bonitas de forma rápida e padronizada. Além de permitir que seja disponibilizada junto com o código-fonte num SCM Git, por exemplo, facilitando sua evolução e versionamento. Outro fator, não menos importante, é que a ferramenta permite que nosso foco seja direcionado no design em questão e não no desenho dos diagramas. O PlantUML é compatível com diversas IDEs como IntelliJ, VisualStudio, Atom, Eclipse, entre outras.
A instalação dos plugins do PlantUML no IntelliJ é muito simples. Para isso, basta realizar as seguintes etapas, conforme ilustrado na Figura 1:
- Acessar o menu
configurações(ctrl + alt + s); - Na caixa de pesquisa, procure por
plugins; e - Instale os plugins
PlantUML Integration,PlantUML ParserePlantUML Diagram Generator.
Figura 1. Configurando os plugins do PlantUML no IntelliJ.
Após instalado os plugins em sua IDE, é necessário criar um arquivo com a extensão .puml e "codar" 😀 . Abaixo segue um exemplo de código para gerar um diagrama de sequência UML de um caso de uso fictício e sua imagem após renderizado (Figura 2). Normalmente, mantenho o código dos meus diagramas junto ao código-fonte do respectivo projeto, geralmente num pacote .../docs/diagrams. Os sites Real World PlantUML e Plant UML Basic Examples disponibilizam uma série de exemplos de diagramas UML de diversos tipos que serão bastante úteis para sua aprendizagem. Se preferir, também é possível gerar os diagramas automaticamente a partir do código-fonte Java já desenvolvido. Para isso, é utilizado o plugin instalado, PlantUML Parser.
Figura 2. Diagrama de Sequência exportado pelo plugin PlantUML.
@startuml
autonumber
skinparam LegendBackgroundColor #white
title UC1 - Retrieve System Payments
'list of the actors and participants'
box "App Platform"
actor "Actor" as AC
end box
box "Payment Service" #lightGreen
participant "Payment Service" as PS
database "Database" as DB
end box
'a brief description of the diagram'
legend top
-- \t**Abstract:**\t --
This use case covers the retrieval of all payments available in Payments Microservice.
end legend
note right of AC #plum
**Endpoint**
GET /platform/v1/payments
**Current implementation:**
None.
**Required implementation:**
Inputs:
* paymentType
Outputs:
* responseCode
* List [PaymentsResponse]
State changes:
* No changes to tables in Payments Service
end note
AC -> PS: **HTTP**\nGET /platform/v1/payments
note right of AC
Parameters in URL:
* paymentType = String
end note
activate PS
alt #transparent if paymentType is not null
PS -> DB: SELECT T.* WHERE\nT.PAYMENT_TYPE = paymentType
activate DB
DB -> DB: Retrieve payments
DB --> PS: List of Payments
deactivate DB
alt #transparent if paymentType is valid
PS -> AC: List of Payments
note right of AC
Response Code: 200
end note
else
PS->AC: Error
note right of AC #pink
Response Code: 404
If the payment type is invalid, the
Payment Service will return Not Found error.
end note
end alt
else
PS->AC: Error
note right of AC #pink
Response Code: 400
If the payment type is not send, the
Payment Service will return a Bad Request error.
end note
end alt
@enduml
Ingrid