ブログ
REST APIドキュメントをReDocを使って作成するための導入手順。
APIドキュメントを作るにあたり、なんとも簡単かつ綺麗にかける方法がないだろうか（今更！？）と思い調査していると、
ReDocなるツールを見つけたのでインストールから静的コンテンツによるドキュメント作成までの手順をこちらに記載しておきます。
前提としてはMacでパッケージマネージャとしてyarnが導入されていることになります。
npmでも良いのですが、今回はyarnにしています。
ここは好みと、実際の導入環境によると思います。
なおnpmコマンドのインストールコマンドに読み替えて頂ければインストール可能だと思います。
今回はyarnを使ってグローバルではなく、ローカルにインストールしますのでnpxコマンドが必要となります。
０．npxコマンドが使えるかの確認
$ npm -v 6.4.1 ← 5.2.0以上にバンドルされているので大丈夫
1．redoc、redoc-cliをインストールする。
$ 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 ✨ Done in 0.24s.
２．redoc-cliでドキュメントを作成してみる
APIドキュメントの元となるswagger.yamlは以下を参考に記述します。
petstore.yaml
petstore.yamlを参考にして、redoc.sampleの真下にswagger.yamlを作成してみましょう。
$ pwd redoc.sample $ ls swagger.yaml swagger.yaml
そしてお待ちかねのhtmlファイルとして、APIドキュメントを作成してみましょう。
$ 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) [⏱ 0.479s]
出力されたindex.htmlをブラウザで見ると整形されたAPIドキュメントが出来上がっております。綺麗！！
あとswagger.ymlをredoc-cliの機能でローカルサーバーを立ち上げてhttp経由でも見ることができます。
$ npx redoc-cli serve swagger.yml --watch
{ ssr: undefined,
watch: true,
templateFileName: undefined,
templateOptions: {},
redocOptions: {} }
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0
Server started: http://127.0.0.1:8080
� Watching redoc.sample..../ for changes...
ここまできてhttp://127.0.0.1:8080をブラウザで見るとちゃんとみれます。
–watchオプションをつけることでswagger.ymlを編集してブラウザをリロードすると、変更箇所が反映しています。
気持ちよくかけることは、ドキュメントを書く側に取っては精神衛生上嬉しいですね！！
関連記事
2024.04.08
2023.10.13
2023.10.13