PlantUML - Mermaid 比較（シーケンス図）

## はじめに

[GitHub が Mermaid に対応](https://gigazine.net/news/20220216-github-mermaid/)しました[^1]。

[^1]: Java サーバが必要な PlantUML に比べて JavaScript で済む Mermaid の方がアドバンテージがあるためでしょうか。まあ私もサーバ側の技術選定するなら Mermaid を選びそうな気がします。

シーケンス図の記法を比べてみます。私はもともと PlantUML を使用していたため「PlantUML 使いから見ると、Mermaid では...」という書き方になりがちなのはご容赦ください。

### それぞれの公式

- [PlantUML - シーケンス図の構文と機能](https://plantuml.com/ja/sequence-diagram)
    - [オンラインエディタ](https://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000)
- [Mermaid - Sequence diagram](https://mermaid-js.github.io/mermaid/#/sequenceDiagram)
    - [オンラインエディタ](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNpt0M2qAjEMBeBXidk68wJdKILC1a3bbkJ7dMrtj9YWEfHd7YzjzqwC-U4gebJJFqz4hmtFNNg6OWcJOlKrjXcG_Wq1PKQhKvqD94nGvqMh3Uky6JHq-if-MCNxJDRAMgXMdJz1jfZTpi12n3RH-ykx6RZb_OZ7OgGezhlSZvIt7jggB3G23fQcZ5rLgADNqrVW8r9mHV_N1YuVgp11JWVWJ_E3dCy1pOMjGlYlV3zR_JRZvd5_C2Gl)

## 手軽に導入

手軽に試したい場合、どちらも [Visual Studio Code](https://azure.microsoft.com/ja-jp/products/visual-studio-code/) の拡張機能 [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced) を使えば対応します（以下「VS Code では」と書かれているのは「Visual Studio Code の Markdown Preview Enhanced を使えば」という意味だと思ってください）。したがって、両記法を併記できます。

両者とも Markdown ファイルの中にコードブロックとして記述すれば、レンダリングしてくれます。

標準で HTML への書き出しもできるので、成果物が HTML でよければ、その組み合わせだけで問題ないかと思います。図の部分は出力された HTML に SVG として埋め込まれています。図だけをイメージとして書き出したい場合や、ドキュメントを PDF やその他の形式に出力したい場合は、また別のツールを併用する必要があります。

## 最小基本のシーケンス図

以下、コード例と描画結果を交互に記述していきます。

<pre>```puml
@startuml
A -> B
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    A ->> B : message
&#096;&#096;&#096;
</pre>

![fig01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/4dff1370-41c1-7d8d-0b30-fc9055526801.png)


Mermaid は`: message`の部分を省略できないようです。また、矢印は `->>` と書く必要がありそうです。

PlantUML は`@startuml`と`@enduml`で括るのが冗長に感じますね。すでに<code>```puml</code>で括っているのに。また、シーケンス図と指定しなくてもシーケンス図になってしまうのは、少々違和感が。これは PlantUML がもともとシーケンス図ツールだった（らしい）ことに起因するかも。

## 返り値

Mermaid は、矢印を記述する方向に制約があるようです。そのため、参加者の順序を予め記述しています。

<pre>```puml
@startuml
A &lt;-- B
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    participant A
    participant B
    B -->> A : return
&#096;&#096;&#096;
</pre>

![fig02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/0a868d8a-5aa8-fd81-4ff6-efc4c50cfd53.png)

矢印をどちら向きにも書ける PlantUML の方が直感的な気がしますが、どうせメッセージラベルは行末に書くので、それはどちらの書き方にも違和感がある気がしますね。

## いろいろな矢印

<pre>```puml
@startuml
A -> B : 先端のバリエーション
A ->> B
A ->X B
A -\ B
A -/ B
A ->o B
A ->>o B
A -\o B
A -/o B
B -> B
A --> B : 線のバリエーション
A -[#blue]> B
@enduml
```

```mermaid
sequenceDiagram
    A ->> B : message
    A -> B : message
    A -->> B : message
    A -X B : message
    A --X B : message
    A -) B : message（非同期）
    A --) B : message（非同期）
&#096;&#096;&#096;
</pre>

![fig03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/84b2f4bd-a111-b7ba-1607-d9f41f3af0b9.png)

省略しましたが、PlantUML は両端矢印も可能です。しかし Mermaid のような、両端に矢のない線は書くことができないようです（別の図と解釈されてしまう）。

## 参加者の活性化と破棄

~~ほぼ同じ書き方ですが、mermaid は`+`と`-`による省略記法があります。しかしこの場合の`-`は`B`の側に書きたい気が...。~~ 追記：PlantUML にも省略記法があることをコメント欄にて教えてくださいました。コメント欄を参照ください。

<pre>```puml
@startuml
A -> B : instantinate
activate B
A &lt;-- B : dispose
deactivate B
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    A ->> B : instantinate
    activate B
    B -->> A : dispose
    deactivate B
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    A ->>  + B : instantinate
    B -->> - A : dispose
&#096;&#096;&#096;
</pre>

![fig04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/84f74868-818e-d9ff-a884-98ff434d243f.png)

## 注釈・コメント

どちらもいろいろと位置調整ができます。

<pre>```puml
@startuml
/' 
    このコメントは描画されません
'/
' この行コメントは描画されません
A -> B
note right: 注釈
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    % この行コメントは描画されません
    A ->> B : message
    Note right of B : 注釈
&#096;&#096;&#096;
</pre>

![fig05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/d7b4003b-1fc0-2704-ec1a-afca521d88a7.png)

何故どちらもデフォルトが黄色いんだ（笑）。Post It の所為かな、やっぱり。

コメントは、複数行コメントの対応可否が別れていますね。

Mermaid の行コメントは、公式のドキュメントでは`%%`となっていますが、VS Code 上では`%`だけでもコメント化されました。

## グループ

`loop`、`alt` などの図の一部をグループ化する書き方です。

<pre>```puml
@startuml
A -> B

alt 注釈
    A -> B : message
else
    A -> B : message
end

note over A, B
    上記 alt/else の他、以下のものが同じように記述できます。
        ・opt
        ・loop
        ・par
        ・break
        ・critical
        ・group + 任意のテキスト
end note

@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    A ->> B : message
    alt 注釈
        A ->> B : message
    else
        A ->> B : message
    end
    Note over A, B : 上記 alt/else の他、opt、loop、par が使えます。
&#096;&#096;&#096;
</pre>

![fig06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/11392d73-b6a8-7767-aa27-20e061ccf92a.png)

## 配色テーマの指定

PlantUML は[こちら](https://plantuml.com/ja/theme)を、Mermaid は[こちら](https://zenn.dev/junkawa/articles/zenn-mermaidjs-theme-config)を参照ください。

PlantUML は、公開されているテーマを記述した外部ファイルを持ってきて、それを include して使います。すでに膨大なテーマが用意されています。

Mermaid は、CSS を使用してテーマを変更しますが、デフォルトでいくつかのテーマが用意されているようです。VS Code の設定 `Markdown-preview-enhanced: Mermaid Theme` で変更するか、下記例のように先頭にテーマ名を記述します。

記述例だけ示します。

<pre>```puml
!include puml-theme-&lt;THEME NAME>.puml
@startuml
A -> B
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
%%{init: {'theme': 'neutral' } }%%
sequenceDiagram
    A ->> B : message
&#096;&#096;&#096;
</pre>

HTML に書き出すと、その中に `mermaid.min.js` の置き場所が書かれているので、CSS の追加もできるでしょう。たぶん。

## 参加者の別名

両者同じように別名を定義できます。しかし書き方は逆ですね...。

<pre>```puml
@startuml
participant クライアント as A
participant データベース as B
A -> B : 問い合わせ
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    participant A as クライアント
    participant B as データベース
    A ->> B : 問い合わせ
&#096;&#096;&#096;
</pre>

![fig07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/21d158fd-a8a2-1233-24b1-94e8dcddf125.png)

## 改行

PlantUML は `\n` で、Mermaid は `<br/>` で、それぞれ改行できます。

下記サンプルで、へんなところで改行しているのは、デフォルトの桁揃えを示したいためです。

PlantUML でメッセージをセンタリングしたい場合は、先頭で `skinparam sequenceMessageAlign center` を指定することで可能です。

<pre>```puml
@startuml
participant "クラ\nイアント" as A
participant "データベー\nス" as B
A -> B : 問い\n合わせ
@enduml
&#096;&#096;&#096;

&#096;&#096;&#096;mermaid
sequenceDiagram
    participant A as クラ\<br/>イアント
    participant B as データベー\<br/>ス
    A ->> B : 問い\<br/>合わせ
&#096;&#096;&#096;
</pre>

![fig08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37554/6440ff63-08f6-f7ee-8467-cc94277ee79f.png)

## 書き出し

図は、単独で使用するのではなく文書に挿入して使うことが多いはずなので、Markdown 内に書くことができれば問題ないはずです。しかし多くの職場では未だ Office ソフトの使用を余儀なく[^2]されているかと思います。

[^2]: 滅べばいい。

そんな場合、私は、プレビュー表示から「範囲指定のスクショ」を撮ってコピペしています。面倒なので。どうしてもの場合（図の中のテキストを検索できるようにしたいなど）は HTML 書き出し、SVG 部分だけ抜き出して`.svg`で保存、インポート、をしていたりします。

## おわりに

両者とも、いろいろとカスタマイズできます。詳細はそれぞれの公式を参照ください。PlantUML はインラインでスタイルを変えられるところ便利ですが、Mermaid は CSS を使えるので独自記法を覚えなくて良いという点がメリットでしょうか。

もう一度、それぞれの公式を書いておきます。

- [PlantUML - シーケンス図の構文と機能](https://plantuml.com/ja/sequence-diagram)
    - [オンラインエディタ](https://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000)
- [Mermaid - Sequence diagram](https://mermaid-js.github.io/mermaid/#/sequenceDiagram)
    - [オンラインエディタ](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNpt0M2qAjEMBeBXidk68wJdKILC1a3bbkJ7dMrtj9YWEfHd7YzjzqwC-U4gebJJFqz4hmtFNNg6OWcJOlKrjXcG_Wq1PKQhKvqD94nGvqMh3Uky6JHq-if-MCNxJDRAMgXMdJz1jfZTpi12n3RH-ykx6RZb_OZ7OgGezhlSZvIt7jggB3G23fQcZ5rLgADNqrVW8r9mHV_N1YuVgp11JWVWJ_E3dCy1pOMjGlYlV3zR_JRZvd5_C2Gl)