RapiDoc を使って OpenAPI をドキュメント化する

🍳はじめに

OpenAPI ドキュメントをより見やすくするため、 RapiDoc を使って HTML ビューするのがよさそうだったので紹介。

Table 1. 環境
App	Version
RapiDoc	9.1.3

🍂RapiDoc について

OpenAPI ドキュメントを見やすく表示してくれる JavaScript ライブラリ（MIT ライセンス）。

RapiDoc の特徴

Swagger 2.0 と OpenAPI 3.x.x に対応。
また対応ブラウザは Chrome, FireFox, Safari 。
HTML の <rapi-doc> タグ（カスタム要素）^[1]を使うだけで簡単に利用できる。
他フレームワークと組み合わせて使うことも可能。
見た目については HTML 属性を指定することで様々なカスタマイズができる。
OpenAPI ドキュメント中の Markdown 記法を解釈してくれる^[2]。

などなど。

🧾RapiDoc の使い方

本記事では CDN から RapiDoc を読み込む使い方について紹介する。
インストール不要でさくっと使えるのがすばらしい。

他の使い方（React や Vue での使い方）は公式のクイックスタートやサンプル集を参照。

Example 1. RapiDoc サンプル

必要最小限の HTML ドキュメント

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />    (1)
    <script     (2)
      type="module"
      src="https://unpkg.com/rapidoc@9.1.3/dist/rapidoc-min.js"
    ></script>
  </head>
  <body>
    <rapi-doc   (3)
      (4)
      spec-url="https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.1.0/examples/v3.0/petstore.yaml"
    ></rapi-doc>
  </body>
</html>

1	✔️ RapiDoc を使用する場合は文字エンコーディングを `utf-8` にする。
2	✔️ RapiDoc スクリプトを読み込み。
3	✔️ RapiDoc 用のカスタム要素。　後述する属性によりドキュメントの表示方法をカスタマイズできる。
4	✔️ 表示したい OpenAPI ドキュメントファイルの URL を指定する。

表示サンプル

RapiDoc 用サーバー

ドキュメントを提供する Web サーバーを用意したい場合は Docker イメージを利用するとよさそう。

docker run -it --rm \
  -p 80:80 \
  -e SPEC_URL="http://petstore.swagger.io/v2/swagger.json" \
  mrin9/rapidoc

カスタマイズする

公式ドキュメントがわかりやすいので、サンプル集やAPIリファレンスを見るのがおすすめ。
ここでは簡単な UI カスタマイズ用の属性の一部だけ紹介する。

Table 2. UI カスタマイズする属性の一部
Attribute	Value	Description
spec-url		表示したい OpenAPI ドキュメントファイルのURL。
theme	📌`light` `dark`	表示UIのベーステーマ。より詳細にカラーテーマを指定したい場合は `bg-color` や `primary-color` を使う。
render-style	📌`read` `view` `focused`	API ドキュメントの表示スタイルを指定する。
schema-style	📌`tree` `table`	レスポンスやリクエストのスキーマ表示方法。

カスタマイズした RapiDoc サンプル

😎おわりに

RapiDoc は手軽に使えて見た目よし、なのでうれしい。
今回はかんたんな使い方だけ紹介したものの、

別の HTML を/に挿入したり
API 部分だけを抽出したり
ブランドカラーを変更したり

…etc. と、もっと柔軟にカスタマイズできるので弄りがいがありそう。