GitHub
Design
GitLab
uml

PlatntUMLを使ってMarkdownでAPIドキュメント作成

はじめに

PlantUMLを使うと、APIドキュメントを効率的に公開できることが分かりました。今回はPlantUMLを使って、APIドキュメントを記述する流れをメモしておきたいと思います。

PlantUMLのインストール

brewを使うと簡単にインストールすることができますので、事前にbrewをインストールしておいてください。

$ brew install graphviz
$ brew install plantuml

plantumlで以下のようなチェックサムエラーが発生しました。私の環境の場合はbrew upgradeを行うことで問題が発生しなくなりました。

$ brew install plantuml
==> Downloading https://downloads.sourceforge.net/project/plantuml/1.2018.1/plantuml.1.2018.1.jar
==> Downloading from https://downloads.sourceforge.net/#!/project/plantuml/1.2018.1/plantuml.1.2018.1.jar
######################################################################## 100.0%
Error: SHA256 mismatch

$ brew upgrade
$ brew install plantuml
==> Downloading https://downloads.sourceforge.net/project/plantuml/1.2018.1/plantuml.1.2018.1.jar
==> Downloading from https://jaist.dl.sourceforge.net/project/plantuml/1.2018.1/plantuml.1.2018.1.jar
######################################################################## 100.0%
🍺  /usr/local/Cellar/plantuml/1.2018.1: 4 files, 6.9MB, built in 8 seconds

Atomのplantumlプラグインのインストール

以下の3つのプラグインをインストールします。

  • plantuml
  • plantuml-viewer
  • markdown-preview-enhanced
  1. AtomのPreferenceからInstallを選択
  2. plantumlを入力してパッケージ検索
  3. plantumlとplantuml-viewerをインストール

Screen Shot 2018-03-04 at 6.39.40 PM.png

  1. markdown-preview-enhancedを入力してパッケージ検索
  2. markdown-preview-enhancedをインストール

markdown-preview-enhancedを利用するために、markdown-previewの設定をオフにします。

Screen Shot 2018-03-04 at 9.40.39 PM.png

APIドキュメントの記述

APIドキュメント風に記述して見ました。以下のようにMarkdownの中にplantumlのメタデータを埋め込むことができるので、図をPNGに落とすなどの手間が省けてとても助かります。

Screen Shot 2018-03-04 at 10.26.06 PM.png