はじめ

自分はこれまでソフトウェア開発において仕様書や設計書を作成する際、Enterprise ArchitectというGUIで操作するソフトウェア設計支援ツールを用いてUML図を描いてきました。
必要なコンポーネントをドラッグアンドドロップするだけでUML図を作成できるので簡単なのですが、図のレイアウトは自分の手で微調整しなければならないので少々面倒です。また、それらの図を挿入する先のドキュメント本体はWordやExcelで作成するのですが、ドキュメント本体もUML図も同じ環境で一度に作成する方法はないかと思っていました。
今回いろいろ調べたところ、自分が愛用するエディタであるVisual Studio Codeであれば、Markdownでドキュメントを書くのとUML図の作成を一度にできるということを知ったので、その方法についてメモしておこうと思います。

Markdownで書くメリット

自分が思うMarkdown記法のメリットは以下の通りです。

段落など見た目が統一される。コピペした際にも崩れない。
プログラムのソースコードを見やすく記載できる
テキスト形式なので、GitやSVNのバージョン管理や差分確認、マージがしやすい。
テキスト形式なので、各種プログラムによる処理や自動化に馴染みやすい。

Markdown記法一覧

Markdownの各種記法についてはこちらの記事で分かりやすく紹介されているので参照ください。

qiita.com

www.milkmemo.com

環境構築手順

1. Visual Studio Codeをインストールする

まずはエディタとしてVisual Studio Codeをインストールします。
こちらのサイトからインストーラをダウンロードして実行すればOKです。
Visual Studio Code

2. PlantUMLをインストールする

Visual Studio Codeの拡張機能であるPlantUMLをインストールします。
PlantUMLで検索すれば以下のものが見つかるので、これをインストールして再読み込みで有効にします。

3. Javaをインストールする

PlantUMLを実行するにはJavaの実行環境が必要になります。
そのため、下記の手順でJavaを予めダウンロード、インストールしておきます。

Javaのダウンロードサイトを開く。
「無料Javaのダウンロード」ボタンを押す。
「同意して無料ダウンロードを開始」ボタンを押す。
ダウンロードしたインストーラを実行してインストールします。自分のPCはWindows10 64bit版なので、「jre-8u191-windows-x64.exe」がインストーラになります。

4. Graphvizをインストールする

PlantUMLがUML図を描画するために使用しているソフトウェアであるGraphvizをインストールします。下記の手順でインストーラをダウンロードしてインストールします。

Graphvizのダウンロードサイトを開く。
上部のメニューから「Download」を選択して開く。
自分のPCのOSに合わせて、ダウンロードするインストーラを選ぶ。自分のPCはWindowsなので、Windowsのカテゴリにある「Stable 2.38 Windows install packages」を選ぶ。
「graphviz-2.38.msi」を選んでダウンロードして実行すればOK。

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

Visual Studio Codeの拡張機能であるMarkdown Preview Enhancedをインストールします。
検索すれば下記のものが見つかるので、インストール、再読み込みで有効にします。
この機能をインストールすることで、Visual Studio Code上で編集するMarkdown記法のテキストファイルにPlantUMLのコードを直接記述できるようになり、共通の環境下で文章を書く + UML図の描画をできるようになります。