Dicas de Visual Studio Code: documentações com Mermaid + diagramas de sequência | pt 19
Neste novo artigo (parte 19) retomo a série que venho produzindo com dicas, truques e novidades no uso do Visual Studio Code. Desta vez abordarei o uso do projeto Mermaid como alternativa para a documentação de projetos, utilizando para isto código estruturado na geração de diagramas de sequência e outros tipos de artefatos.
Caso deseje visualizar os conteúdos já publicados (ou mesmo revê-los), acesse os links a seguir:
Dicas de Visual Studio Code: visualizando tokens JWT, executando scripts rapidamente | pt 18
Dicas de Visual Studio Code: suporte a Postman e visualização de JSON como tabelas | pt 17
Dicas de Visual Studio Code: interrompendo a execução de um processo em uma porta local | pt 16
Dicas de Visual Studio Code: testando APIs REST com instruções curl via script | pt 15
Dicas de Visual Studio Code: testando APIs REST via scripts | pt 14
Dicas de Visual Studio Code: criando mapas mentais | pt 13
Dicas de Visual Studio Code: testes com browser interno, geração de GUIDs | pt 12
Dicas de Visual Studio Code: extensões Deprecated, painel Problems, Marketplace | pt 11
Dicas de Visual Studio Code: diagramas para Kubernetes e abrindo arquivos no browser | pt 10
Dicas de Visual Studio Code: criando diagramas de arquitetura | pt9
Dicas de Visual Studio Code: testes de carga e geração de senhas fortes | pt8
Dicas de Visual Studio Code: To-do list e comparação de arquivos | pt7
Dicas de Visual Studio Code: Git Graph e acessando repositórios Git no browser | pt6
Dicas de Visual Studio Code: integração com Git via Terminal e Kubernetes Templates | pt5
Dicas de Visual Studio Code: testes de APIs REST e integração com Azure DevOps | pt4
Dicas de Visual Studio Code: extensões para MongoDB e Git | pt3
Dicas de Visual Studio Code: extensões para Redis e geração de arquivos .gitignore | pt2
Dicas de Visual Studio Code: extensão para Kubernetes | pt 1
O projeto Mermaid: uma visão geral
No vídeo a seguir temos exemplos de utilização do Mermaid a partir do Visual Studio Code, além da integração oferecida pelo GitHub ao utilizarmos esta tecnologia de documentação com arquivos Markdown (extensão .md). Para assistir esse conteúdo gratuito do Canal .NET clique neste link:
Além de diagramas de sequência, o Mermaid também oferece várias outras alternativas como fluxogramas, grafos representando branches do Git, quadrantes, diagramas de classe… No link seguinte você poderá saber mais sobre essas opções:
Na listagem a seguir temos o conteúdo do arquivo Markdown de um projeto que disponibilizei no GitHub, com a seção de código que está entre ```mermaid e ``` correspondendo a um diagrama de sequência do Mermaid que representa um fluxo de autenticação/autorização com JWT em APIs REST:
# ASPNETCore8-MinimalAPIs-JWT-Swagger-Extensions-Mermaid-HttpFiles-Mermaid_ContagemAcessos
Exemplo de API REST para contagem de acessos criada com o .NET 8 + ASP.NET Core + Minimal APIs, empregando extensões definidas em uma Class Library para utilização de JWT (JSON Web Tokens) e de configurações para que o Swagger suporte tokens. Inclui arquivos .http para testes a partir do Visual Studio Code.
---
## Fluxo básico
```mermaid
sequenceDiagram
actor Aplicacao cliente
participant Login endpoint
participant Contador endpoint
Aplicacao cliente->>Login endpoint: POST /login
Note over Aplicacao cliente,Login endpoint: Informar os atributos<br/>userID e password no JSON
alt credenciais validas
Login endpoint-->>Aplicacao cliente: 200 OK com Token JWT retornado
else credenciais invalidas
Login endpoint-->>Aplicacao cliente: 401 Unauthorized
end
Aplicacao cliente->>Contador endpoint: GET /contador
Note over Aplicacao cliente,Contador endpoint: Token jwt informado como 'Bearer Token' no header Authorization
alt Token JWT valido
Contador endpoint-->>Aplicacao cliente: 200 OK com resultado da contagem
else Token JWT invalido ou faltando
Contador endpoint-->>Aplicacao cliente: 401 Unauthorized
end
```No próximo print podemos observar o diagrama gerado, graças ao suporte nativo a Mermaid oferecido pelo GitHub:
O repositório com este exemplo de diagrama de sequência foi disponibilizado no GitHub:
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!
Já a próxima listagem traz um segundo exemplo de uso do Mermaid na geração de um diagrama de sequência, desta vez com o fluxo de build de um mobile app para iOS com o Azure DevOps:
Novamente será na seção de código iniciada por ```mermaid e ``` que estará o código deste diagrama:
# AzureDevOps-Build-iOS
Materiais de apoio para build de apps iOS no Azure DevOps/Azure Pipelines.
A elaboração desta documentação só foi possível graças ao apoio e dicas que recebi de meu amigo **João Paulo Antunes**. Deixo aqui meu muitíssimo obrigado ao João, por todos os insights valiosos que ele me forneceu sobre o build e a publicação de apps na Apple Store. Agradeço ainda aos amigos **Thiago Bertuzzi** e **Ione Souza Jr.**, que revisaram e sugeriram melhorias no diagrama que disponibilizei aqui.
---
## Fluxo básico
```mermaid
sequenceDiagram
actor Desenvolvedor
participant Azure Repos
participant Azure Pipelines
participant Apple App Store extension
participant InstallAppleCertificate task
participant InstallAppleProvisioningProfile task
participant SDK
Desenvolvedor->>+Azure Repos: git push ou pull request aprovado
Azure Repos->>+Azure Pipelines: Disparar trigger para automação
rect rgb(191, 223, 255)
Azure Pipelines->>+Azure Pipelines: Iniciar execução da automação
Note over Azure Pipelines,Azure Pipelines: Virtual environment baseado em macOS
Azure Pipelines->>+InstallAppleCertificate task: Instalar certificado
Azure Pipelines->>+InstallAppleProvisioningProfile task: Instala um Apple provisioning profile para build em um macOS agent
Azure Pipelines->>+SDK: Restaurar dependências
Note over Azure Pipelines,SDK: Restore usando dotnet, npm, pod install ou xcodebuild
Azure Pipelines->>+SDK: Build do app gerando um arquivo .ipa
Note over Azure Pipelines,SDK: Build usando dotnet, npm, pod install ou mesmo a task Xcode
Azure Pipelines->>+Azure Pipelines: Publicar o arquivo .ipa como um Artifact
end
rect rgb(152, 194, 207)
Azure Pipelines->>+Azure Pipelines: Baixar arquivo .ipa publicado como Artifact
Azure Pipelines->>+Apple App Store extension: Publicar em TestFlight para testes com a task AppStoreRelease
Apple App Store extension->>+Apple App Store extension: Disparar trigger executando automação
Note over Apple App Store extension,Apple App Store extension: O TestFlight é uma plataforma de testes da Apple,<br/>sendo recomendável seu uso antes da subida para Produção
end
```
---
## Azure DevOps / Azure Pipelines
Documentação sobre Virtual Environments: [**link**](https://github.com/actions/runner-images)
A seguir estão indicadas as tasks e extensões referenciadas no diagrama.
### InstallAppleCertificate e InstallAppleProvisioningProfile tasks
Tasks já pré-instaladas por default no **Azure Pipelines**.
### Apple App Store extension
Extensão gratuita, podendo ser instalada via **Marketplace**: [**link**](https://marketplace.visualstudio.com/items?itemName=ms-vsclient.app-store)
Task **AppStoreRelease**:
Esse exemplo também está disponível no GitHub:
https://github.com/renatogroffe/AzureDevOps-Build-iOS
Caso achem útil esta segunda solução, peço mais uma vez um ⭐️ no repositório apoiando. Fica ainda o convite para que vocês me sigam lá no GitHub!
Extensões úteis do Visual Studio Code para se trabalhar com Mermaid
São 3 as extensões para VS Code que gostaria de indicar com este artigo:
- Mermaid Markdown Syntax Highlighting
- Markdown Preview Mermaid Support
- Mermaid Preview
A extensão Mermaid Markdown Syntax Highlighting destaca palavras-chaves do Mermaid em arquivos Markdown, contribuindo para facilitar a edição deste tipo de código:
Podemos observar esta capacidade na próxima imagem:
Já a extensão Markdown Preview Mermaid Support permite que um diagrama do Mermaid também seja renderizado ao visualizar um arquivo Markdown:
É o que se nota na imagem a seguir:
Uma outra possibilidade está no uso de arquivos com a extensão .mmd, contendo apenas o código para a geração de um diagrama do Mermaid. Nestas situações a extensão Mermaid Preview tornará possível a visualização do arquivo a partir do Visual Studio Code, bem como sua exportação para formatos como .png , .jpg e .svg:
A imagem a seguir traz a extensão Mermaid Preview em uso:
