Redoc & Redocly 入門
はじめに
この記事では、Redoc を使って OpenAPI 形式の仕様から仕様書を出力する方法や付属の lint ツールを紹介します。混乱しがちな Redocly との関係についても説明します。ただし Redocly の有償プランについては説明しません。
Redoc とは
Redoc は、OpenAPI で書かれた仕様を元に、仕様書を出力するツールです。用途としては Swagger UI かなりと似ていますが、色使いが控えめで洗練されている印象です。
| Swagger UI で生成した仕様書 | Redoc で生成した仕様書 |
|---|---|
 |
 |
Redoc は有償のカスタマイズをしない場合は Swagger UI ほど多機能ではないようです。API の試し打ちといった機能は利用できませんでした。下記のページで自分の OpenAPI 形式のファイルをアップロードし、どのようにレンダリングされるかを確認することができます。
Redocly とは
Redocly Inc. は Redoc と周辺ツールをメンテナンスしている会社です。Redoc の仕様書をビルドするためのツール redocly を提供しています。Redocly 社はRedoc にテーマ追加やホスティング等の機能を加えて、サブスクリプション形式で販売しているようです。インターネット上では Redocly 社がサービスを提供する前の Redoc 単体を前提とした記事が多く、そのことがちょっとした混乱の元となっています。
私は社内のプライベートネットワークに限られた API の仕様書を作るので Redocly のサブスクリプションは必要ないと判断しましたが、大規模でパブリックな API 仕様書を作る場合には検討してみても良いかもしれません。
redocly コマンドの使い方
以前は redoc-cli というコマンド名でしたが、最新版では名前が変わり redocly というコマンド名になっています。redoc-cli は今でも npm でインストール可能ですが、メンテナンスされていないため避けた方が良いでしょう。 npmjs にも下記の記載があります。
DEPRECATED: this package is deprecated. Use npx @redocly/cli build-docs <api> instead.
このセクションで説明するコマンド例は、パス ./openapi/index.yaml に OpenAPI 形式のファイルが配置されている前提とします。
ローカルで使う
まず、手元の YAML または JSON ファイルから仕様書を作成するコマンドを紹介します。nodejs がインストール済みなら npx を使って簡単に使うことができます。例は下記の通りです。
npx @redocly/cli build-docs ./openapi/index.yaml
成功すれば、ファイル ./openapi/redoc-static.html が書き出されます。適当なブラウザでこのファイルを開けば、記事冒頭で紹介したスクリーンショットのように綺麗な仕様書が見られるはずです。
API 仕様が標準的なルールに従っているかどうかを確認する lint コマンドも提供されています。
npx @redocly/cli lint ./openapi/index.yaml
ルールの一覧は下記のサイトで公開されています。かなりの文量があるので、品質の高い API 仕様を目指す場合には役に立ちそうです。ただし、全てのルールに対応するのは骨が折れるでしょう。ルールに違反している場合でもビルドできるので、場合によっては lint のルールを和らげてバランスをとってください。
redocly はサーバーとして起動することもできます。
npx @redocly/cli preview-docs ./openapi/index.yaml
その後 http://127.0.0.1:8080/ にアクセスすれば綺麗に書き出された仕様書を確認できます。このコマンドは、編集中のファイルを検知してリロードします。コマンドの詳細は下記のドキュメントで確認してください。npx を使わないでインストールする方法も紹介されています。
Docker で使う
ローカル環境にインストールしたくない場合は Docker イメージを使うこともできます。コマンド例は下記の通りです。
docker container run --rm -v ./openapi/:/spec redocly/cli build-docs index.yaml
lint の例は下記の通りです。
docker container run --rm -v ./openapi/:/spec redocly/cli lint index.yaml
サーバーとして起動する例は下記の通りです。
docker container run --rm -p 8080:80 -v ./openapi/:/usr/share/nginx/html/swagger/ -e SPEC_URL=swagger/index.yaml redocly/redoc
その後 http://127.0.0.1:8080/ にアクセスすれば綺麗に書き出された API 仕様を確認できます。手元で実験したところ、この方法では、ソースコードを編集してもブラウザがキャッシュを返してしまいました。その場合は、ブラウザのスーパーリロードを試すと最新のビルドが得られました。
イメージの詳細については下記ドキュメントで確認してください。
Discussion