PlantUMLの使い方完全ガイド｜VS Code設定・主要ダイアグラムの書き方とMermaid比較

SHARE

システム設計書や技術仕様書を作成する際、GUIの作図ツールで四角形や矢印の位置合わせに時間を取られたり、仕様変更のたびに画像を作り直してGitで差分が追えず困った経験はないでしょうか。

そのような作図の課題を一挙に解決してくれるのが、テキストコードから各種UML図を自動生成するオープンソースツールPlantUMLです。テキストで記述するため、Gitでの差分追跡やレビューが容易になり、レイアウトも自動で美しく整列されます。

本記事では、PlantUMLの基本概要やMermaidとの違い、VS Codeでの環境構築手順（Java・Graphviz・拡張機能）、プレビューや画像エクスポートなどの基本操作、コピペで即動作する主要ダイアグラムの構文サンプル、そしてトラブル対処法までを分かりやすく解説します。

PlantUMLとは？テキストでダイアグラムを描く3つのメリット

PlantUMLは、シンプルなテキスト形式のコードからUML図をはじめとする多彩なダイアグラムを自動描画するオープンソースの作図ツールです。

従来の手動ドラッグ＆ドロップによる作図ツールと比較して、ソフトウェア開発現場でPlantUMLが支持されている理由は主に3つあります。

1. バージョン管理（Git）と差分比較（Diff）が容易

PlantUMLを採用する最大のメリットは、Gitなどのバージョン管理システムとの親和性が極めて高い点にあります。

PNGやJPEGなどのバイナリ画像ファイルは、変更があってもGit上でどこが変わったのかテキスト差分（Diff）として確認できません。そのため、設計変更の履歴を追跡することが難しく、Pull Requestでのコードレビューにも不向きでした。

一方、PlantUMLはすべてプレーンテキストで記述されるため、変更箇所が行単位で明確に可視化されます。例えば、「シーケンス図に認証APIの呼び出し処理が1行追加された」「クラス図に新しいフィールドが定義された」といった差分が一目で把握できます。

ソースコードと同じPull Requestのフロー内で設計書の変更をレビューできるため、設計ドキュメントの形骸化を防ぎ、常に最新かつ正確な状態を保ちやすくなります。

2. レイアウトの自動配置で設計作業に集中できる

PlantUMLを使うことで、面倒な座標合わせや矢印の引き直し作業から解放され、設計の本質的な思考に集中できます。

一般的なGUI作図ツールでは、要素を1つ追加したり名前を変更したりするたびに、周囲の四角形を手動で移動させ、折れ曲がった矢印を水平・垂直に揃え直すといった付帯作業が発生します。図が複雑になるほど、レイアウトの微調整だけに多くの時間を費やしてしまいがちです。

PlantUMLは背後でレイアウト描画エンジン（Graphviz）が機能しており、要素同士の接続関係やメッセージの順序を記述するだけで、最適な配置を自動計算して描画してくれます。

要素の追加や削除を行っても、ツール側が自動的に全体のレイアウトを美しく再構成してくれるため、作図作業のストレスを大幅に削減できます。

3. ドキュメント（Markdown）とのシームレスな統合

3つ目のメリットは、Markdownファイルやプロジェクト内のドキュメントとシームレスに統合できる点です。

近年は「Diagrams as Code（コードとしての図面管理）」というアプローチが広く普及しており、仕様書やREADMEなどのテキストドキュメントと同じリポジトリ・同じディレクトリ構造の中で図面データを管理することが標準化しつつあります。

PlantUMLであれば、ドキュメントのソースコードのすぐ隣に .puml ファイルを配置したり、Markdownファイル内にコードを埋め込んだりすることが可能です。

仕様書と設計図面が同じ場所でテキスト管理されるため、リポジトリをクローンした開発者全員が同じ環境で即座に図面を閲覧・編集でき、開発チーム全体のコラボレーション効率が飛躍的に向上します。

PlantUMLとMermaidの違い・選び方の基準

テキストから作図を行うツールとしては、近年WebサービスやMarkdownビューアで広く普及しているMermaid（マーメイド）も有力な選択肢です。

どちらのツールを採用すべきか迷う方のために、2つのツールの主要な違いを比較表にまとめました。

比較項目 PlantUML Mermaid
レンダリング方式・エンジン Java + Graphviz（ローカルまたは専用サーバー） JavaScript（ブラウザ側で即時描画）
GitHub / Notion 標準対応 非対応（外部拡張機能や画像変換が必要） 標準対応（コードブロックを書くだけで表示可能）
環境構築の手間 JavaやGraphvizのインストールが必要 特別なインストール不要（ブラウザ上で完結）
対応ダイアグラムの種類 UML全般、ER図、マインドマップ、WBS、C4モデルなど極めて豊富 フローチャート、シーケンス図、クラス図、ガントチャートなど主要な図
表現力・カスタマイズ性 極めて高い（skinparam、詳細なスタイリング、マクロ対応） シンプル（手軽さ優先、細かい配置制御は限定的）
ファイル分割・共通化 !include による部品化・共通スタイル呼び出しが可能 基本的に1ファイル完結（分割インクルードは非対応）

それぞれの長所を踏まえた選び方の基準は以下の通りです。

  • Mermaidが適しているケース
    READMEやGitHubのIssue、Notionドキュメントなどで手軽にフローチャートや簡単なシーケンス図を共有したい場合。ローカル環境にJavaなどの実行基盤をセットアップせず、Webブラウザ単体で手早く作図したいプロジェクトに適しています。
    手軽にブラウザ単体で作図したい場合は、こちらのMermaidの書き方完全解説の記事をご覧ください。

  • PlantUMLが適しているケース
    厳密なUML仕様に基づいた本格的なシステム設計を行いたい場合や、大規模なクラス図・アクティビティ図を描く場合。また、共通のカラースキームや外部定義ファイルを !include で部品化してチーム全体で統一したいプロジェクトでは、圧倒的な表現力を持つPlantUMLが適しています。

VS CodeでPlantUMLを使うための環境構築3ステップ

VS Codeを使ってローカル環境でPlantUMLを快適に編集・プレビューできるようにするためのセットアップ手順を、3つのステップに分けて解説します。

ステップ1：Java実行環境（JRE/JDK）のインストール確認

PlantUMLはJavaアプリケーションとして動作するため、PC上にJava実行環境（JREまたはJDK）が必要です。

まずは、お使いの端末にJavaがインストールされているかどうかを確認しましょう。

VS Codeの統合ターミナル（またはWindowsのコマンドプロンプト / macOSのターミナル）を開き、以下のコマンドを実行します。

java -version

バージョン情報（例: openjdk version "17.0.x" など）が出力されれば、すでにJavaが導入されているため追加作業は不要です。

もし「コマンドが見つかりません」や「’java’ は内部コマンドまたは外部コマンドとして認識されていません」といったエラーが表示された場合は、Javaをインストールする必要があります。オープンソースで広く利用されている「Eclipse Temurin（Adoptium）」の公式サイトから、お使いのOSに合ったインストーラーをダウンロードしてインストールを完了させてください。

ステップ2：Graphvizのインストールとパス設定（Windows / macOS）

PlantUMLでシーケンス図以外のダイアグラム（クラス図、アクティビティ図、コンポーネント図など）を描画するには、レイアウトエンジン「Graphviz」の導入が必須です。

OSごとのインストール手順は以下の通りです。

macOSの場合

パッケージマネージャーのHomebrewを利用して簡単にインストールできます。ターミナルで以下のコマンドを実行してください。

brew install graphviz

インストール完了後、dot -version を実行してバージョン情報が表示されることを確認します。

Windowsの場合

Windows環境では、標準のパッケージマネージャーであるwingetを利用するのが最もスムーズです。PowerShellまたはコマンドプロンプトを管理者権限で開き、以下のコマンドを実行します。

winget install Graphviz.Graphviz

公式サイトからインストーラー（.exe）をダウンロードして手動インストールする場合は、セットアップウィザード内のオプションで「Add Graphviz to the system PATH for all users（またはcurrent user）」に必ずチェックを入れてください。

インストール完了後、新しいコマンドプロンプトを開いて dot -V を実行し、Graphvizのバージョンが出力されればパス設定は完了です。

ステップ3：VS Code拡張機能「PlantUML」の追加と推奨設定

最後に、VS Code上でシンタックスハイライトやプレビュー機能を利用できるように拡張機能を導入します。

  1. VS Codeのサイドバーにある「拡張機能」アイコンをクリックします（ショートカット: Ctrl + Shift + X / Cmd + Shift + X）。
  2. 検索バーに「PlantUML」と入力します。
  3. 作者が「jebbs」と表示されているPlantUML拡張機能を選択し、「インストール」をクリックします。

インストールが完了したら、必要に応じてVS Codeの設定ファイル（settings.json）を確認・調整します。基本的にはデフォルト設定のままでもローカルのJavaとGraphvizを自動検出して動作しますが、明示的にローカル描画を指定したい場合は以下の設定を追記します。

{
  "plantuml.render": "Local",
  "plantuml.exportOutDir": "./out"
}

plantuml.exportOutDir を指定しておくと、画像エクスポート時に出力ファイルが ./out フォルダに自動整理されるため便利です。

VS Codeでの基本操作（プレビュー・画像保存）

環境構築が完了したら、実際にPlantUMLファイルを作成してプレビュー表示と画像エクスポートを行ってみましょう。

PlantUMLファイルの拡張子は通常 .puml または .wsd を使用します。ファイルを作成したら、コードの先頭に @startuml、末尾に @enduml を記述するのが基本ルールです。

プレビュー表示ショートカット（Alt + D / Option + D）

コードの編集内容をリアルタイムに確認するには、プレビューショートカットキーを活用します。

.puml ファイルをエディタで開いた状態で、以下のショートカットキーを押します。

  • Windows / Linux: Alt + D
  • macOS: Option + D

エディタの右側にプレビューペインが開き、ダイアグラムが描画されます。

このプレビュー機能はエディタ上のテキスト編集と連動しており、コードを書き換えて保存（またはカーソル移動）すると、数秒でプレビュー画面が自動的に再描画されます。構文エラーがある場合はプレビューペイン上にエラー箇所の行番号と原因が表示されるため、即座に修正が可能です。

PNG・SVG・PDF形式でのエクスポート操作

作成したダイアグラムを仕様書に貼り付けたりチームメンバーに配布したりするために、画像ファイルとして書き出します。

画像エクスポートの手順は以下の通りです。

  1. エクスポートしたい .puml ファイルを開いた状態で、コマンドパレットを開きます（Windows: Ctrl + Shift + P / macOS: Cmd + Shift + P）。
  2. 入力欄に PlantUML: Export Current Diagram と入力して選択します。
  3. 出力形式の選択メニューが表示されるので、目的のフォーマットを選択します。

主な出力形式の特徴は以下の通りです。

  • PNG: ビットマップ形式。SlackやTeamsなどのチャットツール、一般的なスライド資料に貼り付ける際に扱いやすい形式です。
  • SVG: ベクター形式。拡大・縮小しても文字や線が一切ぼやけないため、Webページや高解像度ドキュメントへの埋め込みに最適です。
  • PDF: 印刷用資料やクライアント提出用ドキュメントに適しています。

エクスポートが完了すると、設定した出力先ディレクトリ（デフォルトでは同階層または out フォルダ）に画像ファイルが生成されます。

【コピペで使える】主要ダイアグラムの書き方と文法サンプル

実務のシステム開発で特によく使われる3つの主要ダイアグラム（シーケンス図・クラス図・アクティビティ図）について、基本的な文法解説とコピペしてすぐに試せる実践コードを紹介します。

1. シーケンス図（参加者定義・メッセージ送受信・alt分岐・loop繰り返し）

シーケンス図は、システムやオブジェクト間でのメッセージのやり取りを時系列で整理するダイアグラムです。API連携のシーケンスや業務フローの可視化に威力を発揮します。

基本文法のポイント

  • actor（人・ユーザー）や participant（システム・サービス）で参加者を定義します。as 別名 を使うとコード内を短縮名で記述できます。
  • メッセージ送信は同期処理を実線矢印 ->、戻り値や応答を破線矢印 --> で記述します。
  • 冒頭に autonumber と書くだけで、メッセージに連番（1, 2, 3…）が自動採番されます。
  • 条件分岐は alt 条件名 〜 else 代替条件 〜 end で表現します。
  • 繰り返し処理は loop ループ条件 〜 end で表現します。
  • activate 参加者 と deactivate 参加者 を挟むと、実行中のアクティブバー（縦長の矩形）を表示できます。

実践サンプルコード

@startuml
autonumber

actor "ユーザー" as User
participant "フロントエンド" as Client
participant "APIサーバー" as Server
database "データベース" as DB

User -> Client : ログインフォーム送信(ID, パスワード)
activate Client

Client -> Server : POST /api/login
activate Server

Server -> DB : ユーザー情報の取得SQL
activate DB
DB --> Server : ユーザーレコード返却
deactivate DB

alt 認証成功（パスワード一致）
    Server --> Client : 200 OK (JWTアクセストークン発行)
    Client --> User : マイページ画面へリダイレクト
else パスワード不一致
    Server --> Client : 401 Unauthorized (エラーコード)
    Client --> User : 「ログイン情報が正しくありません」を表示
end

loop トークンの生存監視（10分ごと）
    Client -> Server : GET /api/session-check
    Server --> Client : 200 OK (Active)
end

deactivate Server
deactivate Client
@enduml

2. クラス図（クラス定義・属性とメソッド・可視性記号・継承関係）

クラス図は、オブジェクト指向プログラミングにおけるクラスの構造や、クラス同士の依存・継承関係を静的に表現するダイアグラムです。

基本文法のポイント

  • class クラス名 { ... } や interface インターフェース名 { ... } で型を宣言します。
  • 属性（フィールド）やメソッドの前にアクセス修飾子（可視性記号）を付けます。
    • + : public
    • - : private
    • # : protected
    • ~ : package private
  • クラス間の関係性を表す記号は以下の通りです。
    • <|-- : 継承（汎化）
    • <|.. : インターフェース実装（実現）
    • *-- : コンポジション（強固な所有関係）
    • o-- : 集約（緩やかな包含関係）
    • --> : 関連・依存

実践サンプルコード

@startuml
interface Payable {
    + calculateSalary(): int
}

abstract class Employee {
    - id: String
    - name: String
    # baseSalary: int
    + getId(): String
    + getName(): String
    + {abstract} performDuty(): void
}

class FullTimeEmployee {
    - bonus: int
    + performDuty(): void
    + calculateSalary(): int
}

class PartTimeEmployee {
    - hourlyWage: int
    - workingHours: int
    + performDuty(): void
    + calculateSalary(): int
}

class Department {
    - departmentName: String
    - staffList: List<Employee>
    + assignEmployee(emp: Employee): void
    + getDepartmentCost(): int
}

Employee <|-- FullTimeEmployee
Employee <|-- PartTimeEmployee
Payable <|.. FullTimeEmployee
Payable <|.. PartTimeEmployee
Department *-- Employee
@enduml

3. アクティビティ図（新構文による処理フロー・条件分岐・スイムレーン）

アクティビティ図は、ビジネスプロセスやプログラムの実行ロジックをフローチャート形式で可視化するダイアグラムです。PlantUMLでは、読みやすく直感的な「新構文（beta-syntax）」が標準として利用されています。

基本文法のポイント

  • 処理の開始は start、終了は stop で記述します。
  • 各アクティビティ（処理ステップ）は :処理内容; のようにコロンとセミコロンで囲みます。
  • 条件分岐は if (判定条件) then (真のラベル) ... else (偽のラベル) ... endif の形式で記述します。
  • |レーン名| を記述するとスイムレーン（レーン分け）を作成でき、誰がどの処理を担当するのかを一目で分かるように整理できます。

実践サンプルコード

@startuml
|ユーザー|
start
:商品詳細ページを開く;
:「カートに入れる」ボタンをクリック;

|ECシステム|
:カート内商品の在庫数を照会;
if (在庫は十分にあるか?) then (yes)
    :カート画面へ遷移;
else (no)
    :「在庫不足」アラートを表示;
    |ユーザー|
    :購入数量を変更または諦める;
    stop
endif

|ユーザー|
:注文確定ボタンを押下;

|決済サービス|
:クレジットカード決済の処理を実行;
if (決済が承認されたか?) then (承認)
    :決済完了通知を送信;
else (拒否)
    |ECシステム|
    :決済エラー画面を表示;
    stop
endif

|ECシステム|
:注文データを確定保存;
:注文完了メールをユーザーへ配信;

|ユーザー|
:注文完了画面を確認;
stop
@enduml

MarkdownファイルにPlantUML図を埋め込むベストプラクティス

作成したPlantUMLのダイアグラムをMarkdownドキュメントや仕様書に組み込んで運用する際、実務で推奨されるアプローチを3点紹介します。

1. Markdown拡張機能を使った直接記述

VS Codeでドキュメントを執筆する場合、「Markdown Preview Enhanced」などの多機能プレビュー拡張機能を導入すると、Markdownファイル内に直接PlantUMLコードブロックを記述して描画できます。

ローカル環境での編集作業においては最も手軽ですが、GitHubやGitLabなどのWebビュー上では標準レンダリングされない点に留意が必要です。

2. SVG画像として書き出して相対パスで参照する運用（推奨）

チーム開発や社内外へのドキュメント共有において最も堅牢で推奨される運用法は、.puml から生成したSVGまたはPNG画像をMarkdownファイル内で相対パス参照するアプローチです。

例えば、以下のように画像リンクを記述します。

![認証シーケンス図](./images/auth_sequence.svg)

この方法の利点は、GitHubのWebブラウザ画面、Notion、各種Wikiサービスなど、外部ツールにドキュメントを読み込ませた場合でも確実に同一の図が表示される点にあります。ベクター形式のSVGを採用すれば、ディスプレイの解像度に左右されず常にクリアな文字表示が維持されます。

3. CI/CDパイプラインによる自動レンダリング

ドキュメントの更新頻度が高い大規模プロジェクトでは、GitHub ActionsなどのCI/CDパイプラインを活用して、Pull Request作成時やmainブランチへのマージ時に .puml ファイルからSVG画像を自動生成・コミットするワークフローを組むのが理想的です。

PlantUML公式のDockerイメージを利用すれば、サーバー側にJavaやGraphvizのビルド環境を用意することなく、手動での画像書き出し忘れを防ぐ自動化運用が実現できます。

よくあるトラブルと対処法（プレビューが表示されない・Graphvizエラー）

PlantUMLを使い始める際や環境移行時によく遭遇する代表的なエラーと、その具体的な解決策をまとめました。

トラブル1：「Dot Executable: … Cannot find Graphviz」エラー

クラス図やアクティビティ図を描画しようとした際に、プレビュー画面に「Cannot find Graphviz」という赤いエラーが表示されるケースです。

  • 原因: PC内にGraphvizがインストールされていないか、Graphvizの実行ファイル（dot コマンド）への環境変数PATHが設定されていないことが原因です。
  • 対処法:
    1. ターミナルで dot -V を実行し、正しくコマンドが通るか確認します。
    2. Windowsの場合、環境変数PATHにGraphvizのインストールフォルダ（例: C:\Program Files\Graphviz\bin）が登録されているか確認し、未登録の場合はシステム環境変数のPathに追加します。
    3. パスを通しても解決しない場合は、VS Codeの settings.json に直接Graphvizのパスを指定することも可能です。
         {
       "plantuml.commandArgs": [
         "-DGRAPHVIZ_DOT=C:/Program Files/Graphviz/bin/dot.exe"
       ]
     }
    1. 設定変更後は、環境変数を再読み込みするために必ずVS Codeを完全に再起動してください。

トラブル2：プレビューが真っ白で表示されない・Javaエラーが出る

ショートカットキーを押してもプレビュー画面が真っ白なまま読み込みが終わらない場合や、Javaに関するエラーダイアログが出るケースです。

  • 原因: Javaがインストールされていない、またはVS Codeがシステム上のJavaランタイムを見つけられていない可能性があります。
  • 対処法:
    1. ターミナルで java -version を実行し、Javaがインストールされているか確認します。
    2. システムの環境変数 JAVA_HOME にJavaのインストールディレクトリが正しく設定されているか確認します。
    3. 一時的なトラブルシューティングとして、VS Codeの拡張機能設定で "plantuml.render": "PlantUMLServer" に切り替えることで、外部の公式レンダリングサーバー経由で図が描画されるかテストし、ローカル環境（Java/Graphviz）に問題があるかを切り分けることができます。

トラブル3：日本語テキストの文字化けや豆腐（□）表示

ダイアグラム内に日本語のテキストを記述した際、文字化けしたり四角い記号（豆腐）で表示されてしまうケースです。

  • 原因: ソースファイルの文字コードがUTF-8以外になっているか、PlantUMLがデフォルトで使用しているフォントに日本語フォントグリフが含まれていないことが原因です。
  • 対処法:
    1. VS Code右下のステータスバーを確認し、ファイルエンコーディングが「UTF-8」になっていることを確認します（Shift-JIS等の場合はUTF-8で保存し直します）。
    2. .puml ファイルの先頭、または共通設定ファイル内で skinparam defaultFontName を記述し、OSに標準搭載されている日本語フォントを明示的に指定します。 
         @startuml
     ' Windows向け日本語フォント指定
     skinparam defaultFontName "Yu Gothic UI"
     ' macOS向けの場合は以下を指定
     ' skinparam defaultFontName "Hiragino Sans"

     actor ユーザー
     participant サーバー
     ユーザー -> サーバー : 日本語メッセージの送信
     @enduml

まとめ：テキスト駆動作図で設計ドキュメントを効率化しよう

本記事では、PlantUMLの基本概念からメリット、Mermaidとの違い、VS Codeでの環境構築手順、主要ダイアグラムの実践記法、そしてMarkdownへの埋め込みベストプラクティスまでを網羅して解説しました。

今回の重要ポイントをおさらいしましょう。

  • テキスト作図の優位性: Gitによる差分追跡・コードレビューへの統合、レイアウト自動配置、ドキュメントとの一元管理により、設計書のメンテナンスコストを大幅に削減できます。
  • Mermaidとの使い分け: WebやMarkdown上での手軽な共有ならMermaid、厳密なUML準拠・大規模設計・高度なファイル分割ならPlantUMLを選択するのが最適です。
  • VS Codeとの連携: JavaとGraphvizを整えれば、ショートカットキー（Alt + D / Option + D）によるリアルタイムプレビューと各種画像エクスポートで快適な設計環境が手に入ります。

これまで手作業での作図修正や位置合わせに追われていた方は、ぜひVS CodeにPlantUML拡張機能を導入し、まずは本記事で紹介したシーケンス図のコードをコピペしてプレビューを体験してみてください。テキスト駆動作図の圧倒的なスピードと柔軟性を実感できるはずです。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

前の記事

Obsidianおすすめ神プラグイン15選！導入手順と必須プラ…

次の記事

VitePressの使い方完全ガイド｜Vueベースの爆速Mar…