Qiita での UML 記述
Qiita で PlantUML および mermaid が使用できるようになったということで軽く比較したいと思います。
それぞれの正式な書式については公式サイトをご確認ください。
Pros/Cons
先に PlantUML と mermaid について個人的な見解を述べさせていただきます。
PlantUML シーケンス図
Pros
- 図表が画像で表示される
- 描画パーツを細かく指定できる
Cons
- 対応しているサービス以外、ローカルのエディタ（VS code など）で図表化するためには Java の設定が必要となる
- ちょっと図表が古めかしい
mermaid シーケンス図
Pros
- 図表の文字がテキストとして認識できるためコピペがしやすい
- ローカルのエディタで拡張機能を設定するだけで図表化される
- PlantUML よりモダンな図表
- GitHub で採用されている！
Cons
- 図表を画像化するのに一手間かかる
全体的な書きやすさなどは慣れの部分が大きく、極端に有利不利があるようには思えません。
ただ、やはり GitHub に採用されたという点が今後いちばん界隈に影響しそうなので、PlantUML の資産がなく、新規に始めるのであれば mermaid の方が無難な気がします。
PlantUML.1
```plantumlで開始するだけで、@startuml および @enduml は不要となっています。
終了も```で閉じるだけとなります。
```plantuml
Alice -> Bob: Authentication RequestBob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
```
本文中に上記コードを記述すると以下のように表示されます。
mermaid.1
こちらも同様に```mermaidで開始しますが１行目に図表の種別を記述する必要があります。シーケンス図の場合は sequenceDiagram となります。
終了は```で閉じるだけとなります。
```mermaid
sequenceDiagram
Alice->>Bob: Hello Bob, how are you?
Bob-->>Alice: Great!
Alice-)Bob: See you later!
```
Qiita での mermaid の注意事項として、mermaid という単語を「見出し」として使用できないという制限があるため注意しましょう。
同じシーケンス図の内容ですが、出力された図をマウスで触っていただくと、PlantUML は画像となっており、mermaid はテキストが選択できることが分かると思います。
これは Qiita 上だけではなく、VS Code で拡張機能を使用して生成した場合でも同様になります。
PlantUML.2
エイリアスやアクターなども問題なく対応されています。
```plantuml
actor Alice as A
participant Bob as B
A->>B: Hello Bob, how are you?
B->>A: Great!
```
mermaid.2
```mermaid
sequenceDiagram
actor A as Alice
participant B as Bob
A->>B: Hello Bob, how are you?
B->>A: Great!
```
PlantUML.3
Qiita 上でも並列 par、分岐 alt、条件 opt、繰り返し loop、中断 break が記述できます。
```plantuml
par Alice to Bob
Alice->>Bob: Hello guys, how are you?
alt is sick
Bob->>Alice: Not so good :(
else is well
Bob->>Alice: Feeling fresh like a daisy
end
else Alice to John
Alice->>John: Hello guys, how are you?
opt Extra response
John->>Alice: Thanks for asking
end
loop Additional response
Alice->>John: You're welcome.
break 3 times
John->>Alice: Don’t mention it.
end
end
end
```
mermaid.3
mermaid の場合、Qiita 上では並列 par、分岐 alt、条件 opt、繰り返し loop は記述できますが、中断 break はエラーとなるようです。
```mermaid
sequenceDiagram
par Alice to Bob
Alice->>Bob: Hello guys, how are you?
alt is sick
Bob->>Alice: Not so good :(
else is well
Bob->>Alice: Feeling fresh like a daisy
end
and Alice to John
Alice->>John: Hello guys, how are you?
opt Extra response
John->>Alice: Thanks for asking
end
end
```
PlantUML.4
背景色も標準の方法で対応できます。
```plantuml
par Alice to Bob
Alice->>Bob: Hello guys, how are you?
alt is sick
Bob->>Alice: Not so good :(
else is well
Bob->>Alice: Feeling fresh like a daisy
end
else Alice to John
Alice->>John: Hello guys, how are you?
opt Extra response
John->>Alice: Thanks for asking
end
loop Additional response
Alice->>John: You're welcome.
break 3 times
John->>Alice: Don’t mention it.
end
end
end
```
mermaid.4
mermaid でも背景色を設定することができますが PlantUML のように枠全体を塗るようにはなりません。
```mermaid
sequenceDiagram
par Alice to Bob
rect rgb(173,216,230)
Alice->>Bob: Hello guys, how are you?
alt is sick
rect rgb(140, 230, 140)
Bob->>Alice: Not so good :(
end
else is well
rect rgb(0, 128, 128)
Bob->>Alice: Feeling fresh like a daisy
end
end
end
and Alice to John
rect rgb(255,182,193)
Alice->>John: Hello guys, how are you?
opt Extra response
rect rgb(244, 164, 96)
John->>Alice: Thanks for asking
end
end
loop Additional response
rect rgb(221, 160, 221)
Alice->>John: You're welcome.
end
end
end
end
```
まとめ
以上、ごく簡単になりますが Qiita で PlantUML と mermaid のシーケンス図を記述比較をしてみました。
出力結果だけを見るとやはり mermaid の方がモダンな印象を受けますが、細かい記述をしたい場合は PlantUML に一日の長があるように思われます。
ただ、Qiita 独自ではありますが、break のように使えない機能もあるようなので、詳細まで使い込んでいった場合にどこかで引っ掛かる可能性もあるため、ツールやエディタなど環境次第によって選択肢が変わるかもしれません。
シンプルにまとめたい場合は mermaid、本格的に描き込みたい場合は PlantUML というように用途に合わせて変えるのもありかもしれませんが、資産を活かせなくなりそうなので微妙でしょうか。