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


# PlantUML とは

[PlantUML](http://plantuml.com/ja/) は、UML、またはUML以外の図をテキストで記述するためのオープンソースのツールです。
下記のような図を書くことができます。

- [クラス図](http://plantuml.com/ja/class-diagram)
- [シーケンス図](http://plantuml.com/ja/sequence-diagram)
- [ユースケース図](http://plantuml.com/ja/use-case-diagram)
- [アクティビティ図](http://plantuml.com/ja/activity-diagram-legacy)
- [コンポーネント図](http://plantuml.com/ja/component-diagram)
- [状態遷移図（ステートマシン図）](http://plantuml.com/ja/state-diagram)
- [オブジェクト図](http://plantuml.com/ja/object-diagram)
- [ER図](http://plantuml.com/ja/ie-diagram)

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

# この記事の目標

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

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

# 環境
- MacOS Mojave(10.14.6)
- VSCode 1.36.1
- PlantUML
- graphviz

# インストール

### Homebrew インストール

![スクリーンショット 2019-08-04 23.43.52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/d112836b-4626-ab5e-1d15-c1c823c0d8a6.png)


まずは、[Homebrew](https://brew.sh)が必要です。ターミナルで下のようにコマンドを実行してHomebrewをインストールしてください。

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

使い方は[こちら](https://qiita.com/BlueEventHorizon/items/dfaf6fea03cc3aa64738)にも記載しています。

### VSCode インストール

https://code.visualstudio.com
![スクリーンショット 2019-08-04 23.45.03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/464bd834-cea8-a996-3944-b9747cad01e9.png)


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

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

```bash
$ brew cask install visual-studio-code
```

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

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


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

[VSCodeのオススメ拡張機能 24 選 (とTipsをいくつか)](https://qiita.com/sensuikan1973/items/74cf5383c02dbcd82234#9-plantuml)
[VSCodeの拡張機能 おすすめ(8/14更新)](https://qiita.com/EbXpJ6bp/items/4b87a092a3d6a0ecf595)

### 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サブスクリプション](https://www.oracle.com/java/java-se-subscription/)が必要です。

OpenJDKのインストールの詳細は、[こちら](https://qiita.com/spaciba_h_t/items/c96e96be99596b0a9fe4)を参照すると良いと思います。

オラクルの[FAQ](https://www.oracle.com/java/technologies/javase/jdk-faqs.html)を見ると、下記のように`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になります。

![スクリーンショット 2020-12-20 18.26.32.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/582e26fc-118f-6ecf-40c0-8ef2b53d7515.png)

ただし、上記サイトからダウンロードするとインストーラがなくて面倒なので、brewを使ってインストールします（結局brew・・・）参考記事は[こちら](https://qiita.com/gishi_yama/items/ee3526e7e7a922148333)です。

```zsh
$ brew cask install java
```

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

```zsh
$ brew install openjdk

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

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

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

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

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

```bash
$ 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 をインストールする

https://www.graphviz.org

PlantUMLは、シーケンス図とアクティビティ図以外は DOTを使うらしいので図を描画させるためには、Graphvizが必要になるそうです。 → [参考ページ](https://maku.blog/misc/tech/plantuml/install/)

```bash
brew install graphviz
```

### PlantUML をインストールする

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

![スクリーンショット 2019-08-05 1.35.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/a67ad59b-6cf3-a183-ce40-b400c36c14bd.png)

一番上がPlantUMLです。


# 書き方

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

```
@startuml

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

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

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

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

@enduml
```

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

![honyuurui-neko-hito]
(https://www.plantuml.com/plantuml/png/0/SoWkIImgAStDuU9wEddNavsRNowSfs1JewkhyBXnxUF6oPYYcnutha1MRANmTEUMbtiNeGWzsJlvPNilYj3BnVCVD-vytDIjeOaY_cpjoiUD_MY2p-SiWAZaWZW3f7_p5eWwkCZZnXcFcveVD_N0bOBS1hQz_rbd0uB_SlRk5oitFf-wwcd_TeJeq-PUY85S3gbvAS0W0000)

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

![スクリーンショット 2019-08-05 23.49.13.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/4bbecf54-d98d-fb88-24a4-637cc8ef8a6f.png)

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

```
@startuml

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

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

@enduml
```

![class-composit](
https://www.plantuml.com/plantuml/png/0/SoWkIImgAStDuU9wiRjBGSbGIK5BLnTCFsxkVzoy-N5pv-FcrGfM2e-RDeEvSnytxNZStFoukGDJHzCAa1AG_6RiEhYUxDgba0zIRg2dfwMa03B1Ik7bxBRdMrguk1nIyrA0JW40)

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

```
@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
```

![seq_login](https://www.plantuml.com/plantuml/png/0/dLJBRjD055rdlcBKRiaFe0eLutG54aA5lMc6oiBOLcmAB3rJXK11oO9GgXAaX1AgGbCGge9I11zpCtNw5rp7zQDZ8rLuOLapzvnxpvapNlPye-4_VcGHOgpvJeFUzLY3t7UUqeLx9dkoG1Th-6WQeTJ5GdFDT0tRfzTTLsSMMpTyfkoiEcu49CokKwGX6TSjfyui9DJmgTKKs4t7NZVjj4o19r1TrpHTBq0HYMFVC3nMjdM7kOvdehPd6Mk-g6RNRpkcxSyTC3TGKhf45rTMed49YMoXrMjvuVGgdHsFvLOt1ynlfzZy8bASEuHmu0FWHo2Qm3-2s07n2qGh8qiAKoBRmLLd0oT9NAw4RqxEUeEpO1n-FWb7_R3Jd8kCAWb92B2fQd3KNHm2_mPy3yGFsJwIdM4ucCmENcS3g9Xq47KZRf0T0xAlEW-PVVh-HRZPbzqs19koqmAE7xjv_XoaHEM5awtC6I4O5MHUeC5HoYQHxRVoztRCRR47FWRbd0_zxuCOW3X0_wS_NqBmPVgd9m_VGR0FmGxmhLmhm_9JPKKRbfQgrNyQKMQQai-a6aNEn-c2-0f201-3-3GR1gVVkM9U3flufwvZcpJEb-0dpF9ON8P7LvAvAzc5gG0_ZlCJ9Hc9nBPyFbGFvx8UHUsIn2PLXSmM6YPZvxAUNJ3PwidT3_4jZM_AhByVxat8VpIIerVJIPD4qWXPnZV-DFy2 "seq_login")

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

# Markdownファイル中に挿入する

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

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

@import "test.puml"

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

![スクリーンショット 2019-08-06 0.10.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/5a53c91e-d368-4062-40ee-98fe1756ee88.png)

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

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

![スクリーンショット 2019-08-06 0.11.47.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/37634/6fc579d0-a23d-dde8-6250-2c880b21309b.png)

# おわり