O Mermaid é uma solução baseada em código voltada à geração de gráficos e diferentes diagramas. Trata-se de uma excelente alternativa em cenários de modelagem de software e elaboração de arquiteturas, com suporte a artefatos como fluxogramas, diagramas de classe e sequência, mapas mentais, diagramas de entidade-relacionamento, apenas para citar algumas das possibilidades oferecidas pelo Mermaid.
Normalmente associado ao uso em conjunto com documentos no formato Markdown (extensão .md), artefatos criados com o Mermaid podem ser facilmente renderizados a partir de repositórios no GitHub e Azure DevOps. E já que estamos tratando de código e de um formato open source de documentação, podemos nos valer de assistentes de Inteligência Artificial como o GitHub Copilot para gerar rapidamente diagramas que descrevam algum aspecto relevante dentro de uma arquitetura.
No vídeo a seguir e que foi publicado no canal da AzureBrasil.cloud, apresento na prática o suporte do GitHub Copilot à geração de diagramas do Mermaid. Recomendo fortemente que você assista a este conteúdo que tem menos de 10 minutos (clique neste link para acessar o YouTube), a fim de compreender melhor todo o potencial que um assistente de IA como o Copilot pode nos trazer em uma atividade tão importante como a documentação de projetos (e por vezes tão negligenciada!):
A ideia deste conteúdo foi representar em um diagrama o acesso seguro a APIs REST, partindo para isto do uso de tokens JWT e de um Identity Provider (Microsoft Entra ID, Keycloak). Nesse vídeo também apresento diversas dicas, como extensões do Visual Studio Code úteis ao se trabalhar com Mermaid (syntax highlighting, validação de código, exportação de imagens a partir de diagramas) e discuto ainda possibilidades de adoção desta solução de diagramas em cenários reais.
Assim como em outras situações em que utilizaremos a ajuda da Inteligência Artificial, é importante destacar que nem sempre a resposta produzida por um assistente como o Copilot corresponderá exatamente ao resultado final que imaginávamos. Ajustes sempre se farão necessários, muito embora o grande benefício trazido pela abordagem aqui apresentada esteja em uma maior produtividade.
Confirmando o que destaquei no título deste artigo, podemos em questão de segundos elaborar um diagrama de arquitetura. Trata-se de uma capacidade interessante até mesmo para reuniões de trabalho, em que muitas vezes improvisamos diagramas em ferramentas como Paint e Microsoft Whiteboard a partir de desenhos com um acabamento questionável (e que certamente exigirão um retrabalho posterior).
O diagrama gerado no vídeo pode ser observado no print a seguir:
Que corresponde ao seguinte código em Markdown:
# Mermaid-Copilot
Exemplos de diagramas de Mermaid gerados com auxílio do GitHub Copilot.
## Exemplo de autenticação via JWT
**Dúvida enviada ao Copilot:**
Gere um diagrama de sequência para Mermaid (código) detalhando como seria o fluxo de uma aplicação cliente que consome uma API REST protegida por tokens JWT. O token é obtido a partir de um Identity Provider (Microsoft Entra ID, Keycloak) e, uma vez que a aplicação receba esse token, o mesmo é utilizado para se fazer uma chamada a uma API REST protegida.
```mermaid
sequenceDiagram
participant Cliente
participant ProvedorIdentidade as Provedor de Identidade
participant API as API Protegida
Cliente->>ProvedorIdentidade: Solicita Token JWT (usuário, senha)
ProvedorIdentidade-->>Cliente: Responde com Token JWT
Cliente->>API: Requisição com Token JWT (Authorization: Bearer <token>)
API-->>Cliente: Responde com recurso protegidoprotected resource
O repositório com este exemplo está disponível no GitHub:
renatogroffe
Caso achem útil esta solução, peço por favor um ⭐️ no repositório apoiando. Fica também o convite para que vocês me sigam lá no GitHub!
E como o assunto deste artigo está relacionado à área de Inteligência Artificial, deixo aqui como recomendação o treinamento Azure AI Training Session - promovido pela própria AzureBrasil.cloud - e que acontecerá no dia 09/12/2024 (um sábado). Uma excelente oportunidade para você conhecer mais sobre IA, o suporte do Microsoft Azure a essas soluções e OpenAI em geral. Para saber mais acesse o link seguinte a seguir:
Azure AI Training Session - Sympla
Referências
Mermaid - Documentação Oficial
Dicas de Visual Studio Code: documentações com Mermaid + diagramas de sequência