背景

APIを開発するとき、色々なツールがありどれを使えばいいのか、
それぞれどのような特徴があるのかよくわからず迷いました。

いくつか実際に使ってみた感想をまとめました。
そのうち、それぞれの使い方について別途まとめたいと思います。

設計書編

Swagger

有名なオープンソースフレームワーク。Web API開発する人は結構知っている人も多いかと思います。
Swaggerにはいくつか種類があります。

• Swagger Editor：Web上でプレビューをみながら修正することができる。
• Swagger UI：指定のyaml, jsonファイルを元にAPIリファレンスをWeb上に表示することが可能。叩いてみたいAPIを選択し、Web上から実行することもできる。

お手軽にWebから利用することもできますが、Dockerイメージが転がっているのでローカルにSwaggerコンテナをDocker Hub（Swagger）立てて利用することもできます。使ってみたいけどセキュリティ的にWebから使うって抵抗あるな…という方や、チームで共有するときにSwaggerサーバを1台立てておくと非常に便利で良いと思います。

また、VsCodeをお使いの方は専用のプラグインがあります。
編集するだけであればプラグインで十分かと思います。

Swagger UIでAPIリファレンスを眺めていると、「これそのまんまAPI定義書にしちゃいたいわ」なんて欲が出てきます。そんなときはReDoc(GitHub)がおすすめです。

Swaggerで書いたAPI定義ファイルを良さげなhtmlファイルに変換してくれます。例

そのほかにもSwaggerからドキュメントを生成するツールがいくつかあるようです。
こちら の記事にわかりやすくまとめてくれています。

Re:VIEW

こちらはAPIの設計書と直接的な関係はありませんが、設計書を書くことにおいて非常に便利なツールですので合わせてご紹介します。
API定義を内部で利用するだけであればReDocのようなツールから生成したHTMLファイルだけで良いですが、お客様によってはかっちりとしたAPI設計書の提出を求められる場合があります。

私の職場では設計書はwordで書き上げるのが一般的でしたが、面倒に感じることが多々あります…
そんなときにおすすめなのがRe:VIEWです。

Re:VIEW用のMarkDown形式で書いた文書を良さげにPDF化してくれます。
(他にもたくさんの機能がありますが、PDF化してくれる機能ももっています)

linterなどを利用することにより文書校正も可能です。
専用のDockerファイルもありますので、面倒な環境構築もすることなく利用が可能です。
(Docker Hub)

Plant UML

こちらもAPIの設計書と直接的な関係はありません。
これを知ってるかどうかで設計書修正のコストをだいぶ下げることができる（かもしれない）と思います(plantUML公式HP)。

シーケンス図やクラス図をコードベースで書くことができます。
設計内容をコード化することでGitでの管理が可能となるのが大きな利点だと思います。

手書き風とか色を変えたりとか、見た目も少しいじることができます。
似たようなものにmermaid jsというものがあります。

この辺は好みかと思います。

まとめ

• API全体の構成やユースケースの設計：PlantUML, mermaid js
• APIリファレンスやモックの作成：Swagger, (必要に応じて)ReDoc
• お客様へ別途資料の提出が必要な場合：Re:VIEW

というような使い分けが良いかと思います。