APIドキュメントを作るにあたり、なんとも簡単かつ綺麗にかける方法がないだろうか（今更！？）と思い調査していると、
ReDocなるツールを見つけたのでインストールから静的コンテンツによるドキュメント作成までの手順をこちらに記載しておきます。

前提としてはMacでパッケージマネージャとしてyarnが導入されていることになります。
npmでも良いのですが、今回はyarnにしています。
ここは好みと、実際の導入環境によると思います。
なおnpmコマンドのインストールコマンドに読み替えて頂ければインストール可能だと思います。

今回はyarnを使ってグローバルではなく、ローカルにインストールしますのでnpxコマンドが必要となります。

０．npxコマンドが使えるかの確認

1．redoc、redoc-cliをインストールする。

1 2 3 4 5 6 7 8 9 10 11 12

$ mkdir redoc.sample　　 $ cd redoc.sample　　 $ yarn add redoc　　←　redocのインストール $ yarn add redoc-cli　　←　redoc-cliのインストール $ yarn list redoc  ←　入ったかを確認する。 warning package.json: No license field warning No license field warning Filtering by arguments is deprecated. Please use the pattern option instead. ├─ redoc-cli@0.9.5 │  └─ redoc@2.0.0-rc.21 └─ redoc@2.0.0-rc.20 <img draggable="false" class="emoji" alt="" src="https://s.w.org/images/core/emoji/12.0.0-1/svg/2728.svg">  Done in 0.24s.

２．redoc-cliでドキュメントを作成してみる

APIドキュメントの元となるswagger.yamlは以下を参考に記述します。
petstore.yaml

petstore.yamlを参考にして、redoc.sampleの真下にswagger.yamlを作成してみましょう。

そしてお待ちかねのhtmlファイルとして、APIドキュメントを作成してみましょう。

1 2 3 4 5

$ npx redoc-cli bundle swagger.yml -o index.html [ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0 Prerendering docs   � bundled successfully in: aaa/index.html (1059 KiB) [<img draggable="false" class="emoji" alt="" src="https://s.w.org/images/core/emoji/12.0.0-1/svg/23f1.svg"> 0.479s]

出力されたindex.htmlをブラウザで見ると整形されたAPIドキュメントが出来上がっております。綺麗！！

あとswagger.ymlをredoc-cliの機能でローカルサーバーを立ち上げてhttp経由でも見ることができます。

ここまできてhttp://127.0.0.1:8080をブラウザで見るとちゃんとみれます。
–watchオプションをつけることでswagger.ymlを編集してブラウザをリロードすると、変更箇所が反映しています。

気持ちよくかけることは、ドキュメントを書く側に取っては精神衛生上嬉しいですね！！