【リドック】

ReDoc とは?

最終更新:
💡 APIドキュメントを雑誌のように美しく仕上げる職人

OpenAPI(旧Swagger)の定義からAPIリファレンスを生成するオープンソースツール。Redocly社が開発し、3カラムのレイアウトで読みやすいドキュメントを作成できる。

📌 このページのポイント
ReDoc の3カラムレイアウト ナビゲーション Users Products GET /products POST /products Orders Authentication 説明・パラメータ GET /products 商品一覧を取得します category (query) - string limit (query) - integer レスポンス 200 400 コード例 curl -X GET \ /api/products \ -H "Accept: json" // Response 200 {"id": 1, "name": "Product", "price": 1980} 左カラム 中央カラム 右カラム OpenAPI定義から自動生成される3カラムレイアウト
ReDocの3カラムレイアウトのイメージ
ひよこ ひよこ
ReDocってSwagger UIと何が違うの?
ペンギン先生 ペンギン先生
Swagger UIはドキュメントを見ながらAPIを実際に呼び出して試せるのが得意で、ReDocは「読む」ためのリファレンス作りが得意だよ。ReDocは3カラムレイアウトで、左にメニュー、中央に解説、右にリクエストとレスポンスの例が並ぶんだ
ひよこ ひよこ
3カラムレイアウトってどんな感じなの?
ペンギン先生 ペンギン先生
左のメニューには検索欄があって、スクロールするとメニューの位置も連動するよ。説明を読みながら右側ですぐ例を確認できるから、エンドポイントが多いAPIでも目的の場所を探しやすいんだ
ひよこ ひよこ
導入は簡単なの?
ペンギン先生 ペンギン先生
簡単だよ。HTMLに<redoc spec-url="定義ファイルのURL">というタグとscriptタグを書けば表示できる。Redocly CLIの「npx @redocly/cli build-docs openapi.yaml」を使えば、1つのHTMLファイルに出力することもできるんだ
ひよこ ひよこ
Swagger UIとReDoc、どっちを使えばいいのかな?
ペンギン先生 ペンギン先生
その場でAPIを呼び出して試したいならSwagger UI、読みやすいリファレンスを公開したいならReDoc、という目的で選ぶといいよ。同じOpenAPI定義から両方を作れるから、開発中の動作確認はSwagger UI、公開用はReDocのように併用することもできるんだ
ひよこ ひよこ
カスタマイズはどのくらいできるの?
ペンギン先生 ペンギン先生
テーマ設定で色やフォントなどを変更できるよ。x-tagGroupsという拡張を使えば、サイドメニューのタグをカテゴリごとにまとめることもできるんだ。ロゴはx-logoという拡張で指定できるよ
もっと詳しく知りたい人へ

ReDocでAPIのリクエストを実際に送って試せる?

オープンソース版(Redoc CE)のREADMEに並ぶ機能は、3カラムの表示、検索、x-tagGroupsによるメニューのグループ化などで、APIを呼び出すコンソールは含まれていないよ。試しながら読みたい場合は、Swagger UIのように「APIのリソースを見て操作できる」ツールを併用するか、開発元の有償製品の機能を確認しよう。

ペンギン
まとめ:ざっくりこれだけ覚えればOK!
「ReDoc」って出てきたら「OpenAPIからきれいなドキュメントを作るツール」と思えればだいたいOK!
📖 おまけ:英語の意味
「ReDoc」 = 製品名
💬 名前の由来を説明した公式の資料は見当たらないよ。開発元はRedocly社で、今の公式表記は「Redoc」(オープンソース版はRedoc CE)なんだ

参考資料

← 用語集にもどる