設計ドキュメント（UML）をPlantUMLで書いてみる

PlantUML とは

PlantUML は、UML、またはUML以外の図をテキストで記述するためのオープンソースのツールです。
下記のような図を書くことができます。

• クラス図
• シーケンス図
• ユースケース図
• アクティビティ図
• コンポーネント図
• 状態遷移図（ステートマシン図）
• オブジェクト図
• ER図

記述がテキストであることから、GitHubなどのリポジトリーで管理するのに適しています。
これはドキュメントの保守性から言ってとても重要です。
また、既存のファイルからテキストでコピー＆ペーストがし易いことから、同じような設計書を書く場合に効率が高そうです。

この記事の目標

基本設計書では特にクラス図とシーケンス図での記述が重要と考えています。
またER図も書けるようなので、後日これにチャレンジしてみます。

• UMLクラス図を書く
• UMLシーケンス図を書く

環境

• MacOS Mojave(10.14.6)
• VSCode 1.36.1
• PlantUML
• graphviz

インストール

Homebrew インストール

まずは、Homebrewが必要です。ターミナルで下のようにコマンドを実行してHomebrewをインストールしてください。

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

使い方はこちらにも記載しています。

VSCode インストール

https://code.visualstudio.com

Homebrewまたは上記のサイトから取得したインストーラ
を使ってVSCodeをインストールします。

Homebrewでは以下のようなコマンドを実行します。

$ brew cask install visual-studio-code

または、https://code.visualstudio.com/download からインストーラをダウンロードして実行します。

VSCodeには拡張機能をインストールする機能があり、UML、ER図を書くことができるPlantUMLもその内の一つです。

VSCodeには多くの拡張機能がありますので、下記記事などを参考にして便利な拡張機能を入れると良いと思います。リストにはもちろんPlantUMLも含まれています。

VSCodeのオススメ拡張機能 24 選 (とTipsをいくつか)
VSCodeの拡張機能 おすすめ(8/14更新)

Java をインストールする

PlantUMLの実行にはJavaが必要になります。しかしながらOracle Javaライセンスは、2019年4月16日以降のリリースに対して変更されましたので注意が必要です。

OpenJDK
個人利用の場合はOracleJDKでも大丈夫ですが、商用利用の場合は、
https://jdk.java.net
こちらのOpenJDKを利用します。

OracleJDK
https://www.oracle.com/technetwork/java/javase/downloads/index.html
https://www.java.com/ja/download/
こちらのOracleJDKは、個人利用の場合はOKですが、商用利用ではJava SEサブスクリプションが必要です。

OpenJDKのインストールの詳細は、こちらを参照すると良いと思います。

オラクルのFAQを見ると、下記のようにOracle Java SEは permits personal use, development, testing, prototyping, demonstrating and some other uses at no costとあります。

- Oracle OpenJDK releases under the open source GNU General Public License v2, with the Classpath Exception (GPLv2+CPE) (since Java 9), and

- Oracle Java SE product releases, which includes the Oracle JDK for Java 8 and later, and Oracle JRE with Java Web Start in Java 8, under the OTN License Agreement for Java SE. This license permits personal use, development, testing, prototyping, demonstrating and some other uses at no cost.

2020/12/20時点では、最新版はJDK15です。
こちらはOracleJDKと区別するために、OpenJDKと呼ばれていますが、キャプチャー画面左下を見るとわかるように、やはりOracleが主導して提供されている無償のJDKになります。

ただし、上記サイトからダウンロードするとインストーラがなくて面倒なので、brewを使ってインストールします（結局brew・・・）参考記事はこちらです。

$ brew cask install java

または、（M1 Macではこちらじゃないとエラーになるようでした）

$ brew install openjdk

openjdkの場合は、インストール後に表示されるように下記も実行します。

$ sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

上記の２系統のインストールともPATHを通す必要があるので、.zshrcなどに下記を追記します。
15はJDK15の場合なので、適宜読み替えてください。

export JAVA_HOME=`/usr/libexec/java_home -v 15`

バージョンなどを確かめてみます。

$ java -version
openjdk version "15.0.1" 2020-10-20
OpenJDK Runtime Environment (build 15.0.1+9)
OpenJDK 64-Bit Server VM (build 15.0.1+9, mixed mode, sharing)

graphviz をインストールする

PlantUMLは、シーケンス図とアクティビティ図以外は DOTを使うらしいので図を描画させるためには、Graphvizが必要になるそうです。 → 参考ページ

brew install graphviz

PlantUML をインストールする

VSCodeで、⌘+Pを押し、出てくるテキストフィールド内で ext install plantumlと入力します。

一番上がPlantUMLです。

書き方

ファイル名は、filename.pumlとします。filename.puでも大丈夫です。
下記のように <|-- を使うと継承関係が記述できます。

@startuml

哺乳類 <|-- ねこ
哺乳類 <|-- ひと

哺乳類 : 年齢
哺乳類 : 体重
哺乳類 : 食べる()
哺乳類 : 歩く()
哺乳類 : 眠る()

ねこ : 鳴く()
ねこ : じゃれる()

ひと : 住所
ひと : 電話番号
ひと : 働く()

@enduml

option+Dでプレビューできます。

上のファイルは、下記のようなUMLを生成するメニューで作成しています。

その他にもコンポジション、集約の関係も記述できます。
詳しくはこちら
http://plantuml.com/ja/class-diagram

@startuml

人 o-- "0..*" 車 : 集約

車 "1" *-- "1" ハンドル : コンポジション
車 "1" *-- "1" エンジン : コンポジット

@enduml

次に少し複雑なシーケンス図を描いてみます。

@startuml

actor User
box "View" #EEEEBB
  participant AppDelegate
  participant TopView
end box

box "ViewModel" #BBBBEE
  participant LonginViewModel
end box

box "Model" #DDBBDD
  participant LoginUseCase
  participant LoginRepository
end box

participant EndPoint

activate EndPoint #FFBBBB

User -> AppDelegate : 起動

activate AppDelegate #FFBBBB

AppDelegate -> TopView : アクティベート
activate TopView #FFBBBB

note over TopView
    画面遷移管理
end note

TopView ->  LonginViewModel : ログイン可否確認
activate LonginViewModel #FFBBBB

LonginViewModel ->  LoginUseCase : Token有無問い合わせ
activate LoginUseCase #FFBBBB

note over LoginUseCase
    Tokenの管理
end note

LoginUseCase -> LoginUseCase : Token取得
note left
  Tokenはメモリー上に保存とする
end note

alt Token有

     LonginViewModel <<--  LoginUseCase : Token有
     LonginViewModel -> LoginRepository : Tokenのリフレッシュ要求
     activate LoginRepository #FFBBBB
     LoginRepository -> EndPoint : Tokenのリフレッシュ要求
else Token無
     note over TopView, EndPoint
    サインアップ処理
     end note

     LonginViewModel <<--  LoginUseCase : Token無
     TopView <<--  LonginViewModel : サインアップ要求
     TopView -> TopView : 初回起動画面表示

     TopView <<--  LonginViewModel : サインアップ完了
end

@enduml

なかなか本格的に記述できることがわかります。

Markdownファイル中に挿入する

設計書を書くと言う観点から考えると、当然マークダウンで書きたいと思うのは当然です。
VSCodeでは、マークダウンファイルにPlantUMLのファイルを埋め込んだものもプレビューできます。

# 設計書です
## はじめに
これはテスト文書です。

@import "test.puml"

このように表示されます。

Markdown Preview Enhanced をインストールする

このようなマークダウンファイルをプレビューするには、Markdown Preview Enhancedという拡張機能をインストールします。例によって、⌘＋Pを押下し、ext install Markdown Preview Enhancedとします。

おわり