OpenAPI 仕様書を一枚の HTML にまとめる CLI を作ってみた
はじめに
はじめまして、GO で Web エンジニアをしている佐藤です。
普段は、『DRIVE CHART』[1]という交通事故削減支援サービスの開発を担当しています。
今回は、業務でも利用している OpenAPI の仕様書をお手軽に作成できる openapi-generate-html[2] という CLI をご紹介します。
このツールを使うと OpenAPI の定義ファイル（JSON または YAML）から、スタンドアロンな HTML の API ドキュメントが簡単に生成できます。
課題と解決
OpenAPI は、 API のインターフェースを明確にし開発を円滑に進めるために便利なツールです。
一方、開発ドキュメントであるため、社内環境でのみ閲覧可能とすることが多く、社外関係者の共有時に困ることがありました。
- JSON (YAML) は API サーバーから配信しているため、社外からアクセスできない...
- HTML 以外の静的ファイル (JS / CSS) が多く、一式揃えるのが大変...
そこで、 openapi-generate-html の出番です。
このツールを使うと、 出力された一枚の HTML ファイルを渡すのみ でよくなります。
使い方
openapi-generate-html は対話型の CLI です。
-i で OpenAPI のファイルまたは URL を指定するのみで ok です。
npx openapi-generate-html -i openapi.json
ダークテーマにしたいときは --theme=dark を指定します。
npx openapi-generate-html -i openapi.json --theme=dark
その他、細かなオプションは CLI Options をご確認ください。
仕上がり
以下の 6 パターンの中からお好きな見た目をお選びいただけます 👩🎨🎨
| Light | Dark 🧪 | |
|---|---|---|
| Stoplight |
 --ui=stoplight --theme=light
|
 --ui=stoplight --theme=dark
|
| Swagger |
 --ui=swagger --theme=light
|
 --ui=swagger --theme=dark
|
| Redoc |
 --ui=redoc --theme=light
|
 --ui=redoc --theme=dark
|
個人的には Stoplight が 3カラム構成でリクエスト・レスポンス共に見やすくおすすめです。
内部の仕組み
ポータビリティの高い一枚の HTML にするのが、openapi-generate-html のキモですが、それを実現しているのが、 @apidevtools/json-schema-ref-parser です。
OpenAPI は $ref を用いて、ローカルもしくは HTTP 経由でスキーマを参照できる仕様[3] があります。
そのためファイル分割されることが多々あるのですが、その分割されたファイルを $RefParser.bundle で単一の JSON にまとめることが可能です。
import $RefParser from '@apidevtools/json-schema-ref-parser'
// All-In-One JSON
const bundledDocs = await $RefParser.bundle(rawApiDocs)
あとはこの JSON オブジェクトを、ページテンプレートに埋め込むことで、HTML ができあがります。今回は ejs を使って埋め込みをおこなっています。
import ejs from 'ejs'
// All-In-One HTML
const bundledHtml = ejs.render(template, {
jsContent,
cssContent,
apiDocs: JSON.stringify(bundledDocs),
})
非常にシンプルな仕組みであることがお分かりいただけたかと思います。
おわりに
いかがでしたでしょうか。
ローカルで実行してサクッと関係者に渡せたり、CI で実行して S3 や GitHub Pages と言った静的サイトにホスティングできたりと、活用の幅は広いと思いますので是非ご利用ください。
GO では移動の未来をつくるエンジニアを募集しています。
ご興味がある方は下記をご覧になってください。
Discussion