i-Vinci TechBlog
株式会社i-Vinciの技術ブログ

PlantUMLで仕様書をつくりたい

最近炊飯器ではなく土鍋を使い始め、QOLの高まりを感じているi-Vinciの片桐です。
PlantUMLという便利なツールに出会ったのでそのことについてメモがてらに書いてみようと思います。

悩み

仕様書と言えば某表計算ソフトに図や表なども入れずに、びっしり日本語を書き込んでまるで専門書のような仕様書をつくっていた。
すべてを網羅できるのはいいが、システムについてある程度知らなければ読めない、何の情報も得られないものになってしまう...
UML図ならプロジェクトに参戦したてのメンバーも理解しやすいだろうと思ったが、メンテナンスが面倒ならいつか誰も修正しなくなるだろうし...
そんな中テキストだけでUMLが描けるツールを見つけたので試してみた！

PlantUMLとは

Unified Modeling Language 統一モデリング言語 を使用したツール

シーケンス図やユースケース図、状態遷移図などを テキストで書ける便利ツール
Javaを使用したツールで、テキストを解釈して図を作成してくれる
PlantUML公式サイト

メリット

  • テキストで簡単に図を作れる!
  • テキストで管理ができる! (gitで管理できるのでとても良い)

デメリット

  • 環境を作る必要がある（インストール等が必要。オンラインサーバーなどで図を作れるが...）
  • 簡単とは言え言語を使うので敷居がつまさき引っかかるくらいは高いかも？？

テキストで記述するとテキストを解釈して自動で作図をしてくれるツール。矢印だったり、オブジェクトの配置など本質的ではない部分を自動でやってくれる部分にすごく興味を惹かれた。
チームで各々が作ってもフォントが違う、色が微妙に違う、矢印5°傾いているとか本質的ではないのに面倒な悩みから解放されるのはありがたい。
マウスをカチカチするよりキーボードをカタカタしている方が好きな人にもうれしいツールだ。
これを使って仕様書を作れないか試行中。。。UMLの図で仕様書を作成、メンテナンスしていけると最高！
某表計算ソフトを使って作図 → メンテナンス時のバージョン管理に変更履歴やバックアップファイルの作成など面倒事から解放される！されたい！
まずは気になるデメリットから懸念点を洗い出して心置きなくメリットを享受しよう！

環境（オンラインサーバー）

PlantUMLのサイトにはオンラインサーバーがあり、そこで簡単にPlantUMLのすごさを実感できる。さらに作成した図のへのリンクURLも取得できるため便利そう。
ただやはり気になるのは機密情報である。内部の設計書を外に出すのはよろしくないため簡単に試す程度しかできないだろう。

環境（OSにインストールする）

Java, PlantUML, Graphviz(ER図や状態遷移図などの作成に必要）をインストールする必要がある。
開発するだけならばvscodeにPlantUMLの拡張機能を追加するだけで問題ない。vscode上でプレビューも見れる！

最終的な成果物

markdown + PlantUMLでテキストで仕様書を作成する。PlantUMLのテキストから作図して最終的にhtmlファイルやPDFファイルに出力できればよさそう。

デメリットを把握したところで早速使ってみようと思う。

環境構築

windows + vscodeでの構築方法

  • javaインストール
  • Graphvizインストール https://graphviz.org/download/
    インストール後にコマンドを打ち込む必要あり（以下はデフォルトインストールフォルダ、version 2.44.1の場合）
cd c:\Program Files\Graphviz 2.44.1\bin
dot -c
  • vscodeに拡張機能を追加
    • PlantUML
    • Markdown Preview Enhanced (markdownファイルに埋め込みたい場合)
      markdownファイルにPlantUMLファイルを埋め込みたい場合はPlantUMLserverを設定する必要がある。（ローカルならサーバー立ち上げる。オンラインサーバーで良いのならhttps://www.plantuml.com/plantuml を設定する）

実践

環境構築が終わったので試しにシーケンス図を書いてみた。
下のような感じでvscode上でテキストを書く。そしてAlt + Dを押すとプレビューが表示される

@startuml
title りんごを買い逃した人
participant B order 1
participant A order 2
participant 店 order 3

A -> 店 : りんご買います。100円
店 -> A : 税込みで110円です。10円足りないです
A -> B : 10円貸して
B -> A : 3倍にして返せよ
A -> B : せめて1.5倍で勘弁して
B -> A : OK
A -> 店 : りんご買います。110円
店 -> A : すみません。売り切れました
A -> A : OTZ
B -> A : 15円返せよ
A -> B : 返すよOTZ
@enduml

行を入れ替えるだけで表の矢印の上下も入れ替わるのですごく便利！
この記述方法なら特に学習コストの高さを感じない、エクセルやパワーポイントで矢印を作る必要もなくてとても良い！
他にもER図だったりフローチャートなど様々な図をテキストで表現できるのはうれしい。まだ少ししか遊んでいないが、実用できそうな印象を受けている。
自分の知らないツールに触れ、できなかったことや不便な事が解決してく様はとても面白い、わくわくする。そんな自分は生粋のエンジニアなんだと実感している。

最新記事