はじめに

みなさんこんにちは、PlantUML使ってますか？

おそらく多くの人は公式のWEBサーバ、もしくはVSCodeの拡張機能を使っているんじゃないかと思います。

PlantUMLのWEBアプリ(以下、PlantUML-Server)をローカルにホストすることもdocker経由で簡単にできるのですが、PlantUMLの外部ファイル(.iuml)を読み込む際には設定が必要だったのでメモを残しておきます。

PlantUML-ServerのREADMEに書いてあったと言うオチですが、同じシチュエーションになった人の助けになればと思います！

また、Javaやdocker等の操作は初心者なので、間違いがあれば訂正いただけると助かります！！

1. 確認環境

ツール	バージョン
PlantUML-Server	v1.2024.4

2. PlantUML-Serverを立てる

クイックスタートを参考に進めていきます。

dockerのインストールは完了済みの想定です。

まずdocker imageをダウンロードしてきます。

docker pull plantuml/plantuml-server:jetty

次にPlantuml-Serverの動作を確認します。

docker run -d -p 8080:8080 plantuml/plantuml-server:jetty

docker runで使うと便利なオプション

--rm コンテナ停止時に削除します
--name NAME: コンテナの名前をつけます

起動に成功していれば、 http://localhost:8080 でアクセスできるはずです。

3. PlantUMLで外部ファイルを使用する

次にPlantUML (PlantUML-Serverではなく) を使って、複数のファイルで同じ処理を繰り返す場合に、共通部分を他のファイル(以下、外部ファイル: 拡張子は.iuml)に書き出して使用する方法を紹介します。

外部ファイルは、C言語の.hファイルのようなイメージです。

VSCodeを使うのが簡単なので、本項目ではVSCodeの拡張機能を使用していきます。

3.1. PlantUMLで描画（外部ファイルなし）

まず、PlantUMLでシーケンス図を描きます。
(拡張子はなんでも良いので、一般的な.pumlを使用します。)

test-1.puml

@startuml
skinparam ParticipantPadding 50
hide footbox

!procedure $echo($src, $dst, $str)
  $src ->  $dst : $str
  $dst --> $src : echo $str
!endprocedure

$echo(Bob, Alice, "hello")
|||
$echo(Bob, Alice, "world")
@enduml

コードの説明

まずUMLを描画するおまじないと、基本的な図の表示設定を行っています。
```
@startuml
skinparam ParticipantPadding 50
hide footbox
...
@enduml
```
- @startuml~@enduml: 囲った部分がUMLとしてレンダリングされます。
  PlantUML-Serverでは1つしか記述できませんので、最初はとりあえず書くという認識で良さそうです。
- skinparam ParticipantPadding 50: 参加者間(BobとAlice)のパディングを設定しています。
- hide footbox: 図下に表示されるフッターを非表示にしています。
次に簡単なプロシージャを定義します。
```
!procedure $echo($src, $dst, $str)
  $src ->  $dst : $str
  $dst --> $src : echo $str
!endprocedure
```
- !procedure~!endprocedure: 囲った部分がプロシージャとして定義されます。
  C言語の関数のように記載でき、引数をそれぞれ$src, $dst, $strに設定しています。
  詳しくはこちらを参照してください。
最後に先ほど定義したプロシージャを呼び出していきます。
見やすいように|||にて間隔を空けています。
```
$echo(Bob, Alice, "hello")
|||
$echo(Bob, Alice, "world")
```

詳細はPlantUMLの公式サイトを参照してください。

3.2. PlantUMLで描画（外部ファイルあり）

上記ファイル内の設定部分(skinparamやhide footbox)やプロシージャ(!procedure $echo~!endprocedureで囲まれた部分)を外部ファイルに書き出したいと思います。

各ファイルから、!include ファイル名を呼ぶことで使用することができます。
公式ドキュメントにはこちらに記載があります。

今回は以下の2つのファイルを同じディレクトリに入れます。

include.iuml: プロシージャを定義しているファイル。
test-2.puml: プロシージャを呼び出すファイル。
同じような内容をtest-*.pumlに書いていく想定。

include.iuml

@startuml
skinparam ParticipantPadding 50
hide footbox

!procedure $echo($src, $dst, $str)
  $src ->  $dst : $str
  $dst --> $src : echo $str
!endprocedure
@enduml

test-2.puml

@startuml
!include include.iuml

$echo(Dave, Charlie, "Good")
|||
$echo(Dave, Charlie, "Bye")
@enduml

VSCodeの拡張機能なら特に設定せずとも表示されるはずです。

3.3. CLIからjarファイルを実行する場合

余談ですが、PlantUMLを.jarファイルでダウンロードした場合、
コマンドラインからファイルを指定することで画像を出力させます。

この場合、-Dplantuml.path.include=path/to/fileのオプションを設定することでローカルのファイルを読み込めます。公式ドキュメントではこちらです。

java -Dplantuml.path.include=path/to/include.iulm -jar platnuml.jar test-2.puml

4. PlantUML-Server(docker)で別ファイルをIncludeする

dockerでPlantUML-Serverを起動した場合はjavaのコマンドを叩いている訳ではないので、どうやってオプションを設定するか悩みました。

解決方法：
結局は、公式READMEのオプションを設定する方法で解決しました。

まず、環境変数PLANTUML_PROPERTY_FILEに使用する設定ファイルを用意します。

java.properties

plantuml.include.path=/include

指定するパス(上記例では/include)は、ローカルのパスではなく、docker上のマウント先ディレクトリを設定します。

そして設定ファイルと.iumlファイルをディレクトリに格納します。

$tree
.
├── include.iuml
└── java.properties

上記ファイルを同一ディレクトリに格納する必要はないです。
また、マウントではなくコピーを行っても良いですが、後から編集する場合を考えてマウントにしています。

dockerを実行する際に、設定ファイルと外部フォルダがあるフォルダをマウントし、環境変数に設定ファイルのパスを設定します。

docker run -d --mount type=bind,source=.,target=/include -e PLANTUML_PROPERTY_FILE=/include/java.properties -p 8080:8080 plantuml/plantuml-server:jetty

--mount type=bind,source=.,target=/include: ローカルのディレクトリをコンテナにマウントします。-vでも同様の操作が行えます。
-e PLANTUML_PROPERTY_FILE=/include/java.properties: 環境変数に値を設定します。

以上でtest-2.pumlの内容を書けば、無事include.iumlの内容を読み込んでくれるはずです！

最後に

dockerにディレクトリをマウントしているので、ローカルの外部ファイルを変更すればPlantUML-Serverの内容も変更されます。ただし描画は画面左のエディタ内の内容が変更された時にされて、もっと言うとその内容がURLになっています。

キャッシュにより変更が反映されないので、その場合はスーパーリロードが必要です。

PlantUML-Server(docker)で別ファイルを!includeする