Una breve introducción sobre cómo realizar diagramas con la librería mermaid

¡Hola a todos!

En una reciente actualización de MessageViewer @Henrique Dias y yo propusimos una nueva manera de visualizar mensajes en IRIS Interoperability. En esa actualización, intentamos dar a los usuarios una visualización basada en un diagrama de secuencia UML. Tenéis más information en el artículo anterior.

Para conseguir los complicados cálculos geométricos necesarios para realizar ese diagrama, usamos mermaid, una extraordinaria librería JavaScript open source. Y lo que me gustaría compartir con vosotros en este artículo es cómo utilizar esa librería. Me centraré solo en el diagrama de secuencia, pero estad seguros de que la librería permite hacer mucho más.

Mermaid utiliza una sintaxis inspirada en Markdown para definir los diagramas. Es super intuitivo, por eso es mejor mostraros un ejemplo en lugar de escribir un montón de texto aburrido:

sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?

Esta definición permite al motor de mermaid representar el siguiente diagrama, directamente en una página web usando SVG:

Ese ejemplo fue extraído de la documentación de mermaid, y podéis probarlo en este editor online. Hay muchas configuraciones que podéis aprovechar.

Como podéis ver, en la definición del diagrama solo necesitáis especificar los actores/participantes y qué eventos/mensajes se envían unos a otros.

Y todo lo que necesitáis para tener el diagrama en vuestra página web es un contenedor div con la especificación del diagrama y un código JavaScript que inicia el motor de mermaid y representa el diagrama. 

<div class="mermaid">
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
</div>

mermaid.initialize({
    startOnLoad: true,
    theme: 'forest'
});

Podéis encontrar el ejemplo en este enlace.

Este es el frontend base del trabajo propuesto. Para el backend, todo lo que tenemos que hacer es configurar un endpoint REST que recupera mensajes desde una sesión de interoperabilidad de IRIS, los formatea en un objeto JSON adecuado y lo devuelve al frontend. Como el objetivo de este artículo es el código  frontend, no prestaré atención a la implementación en el backend, pero podéis comprobarla en las clases dispatch y service.

El backend devuelve un JSON como este:

{
    "participants":[
        "diashenrique.messageviewer.Service.SendMessage",
        "diashenrique.messageviewer.Operation.ConsumeMessageClass"
    ],
    "messages":[
        {
            "id":"1182",
            "from":"diashenrique.messageviewer.Service.SendMessage",
            "to":"diashenrique.messageviewer.Operation.ConsumeMessageClass",
            "message":"2021-10-05 03:16:56.059 SimpleMessage"
        },
        {
            "id":"1183",
            "from":"diashenrique.messageviewer.Operation.ConsumeMessageClass",
            "to":"diashenrique.messageviewer.Service.SendMessage",
            "message":"2021-10-05 03:16:56.06 NULL"
        }
    ]
}

Finalmente, con unas funciones JavaScript sencillas se puede transformar este JSON en una especificación de diagrama de secuencia de mermaid como este:

sequenceDiagram
autonumber
participant P0 as diashenrique.messageviewer.Service.SendMessage
participant P1 as diashenrique.messageviewer.Operation.ConsumeMessageClass
P0->>P1: 2021-10-05 03:16:56.059 SimpleMessage
P1->>P0: 2021-10-05 03:16:56.06 NULL

Y este es el diagrama de secuencia representado:

Podéis comprobar el código JavaScript completo aquí.

¡Y eso es todo! Espero que este artículo os pueda resultar útil en vuestros increíbles proyectos.

¡Gracias!