Zenn
🕯️

Open API を生成するChrome拡張を妄想する

2023/11/18に公開
Chrome拡張
OpenAPI
idea

直近の仕事でリクエスト／レスポンスの JSON から Open API を作成する必要があります。そのために次のような仕組みを構築しています。

  1. SPAのサイトからブラウザーコンソールでリクエスト／レスポンスのJSONを取得
  2. 取得した JSON をディレクトリベースのルーティングと同じ要領で配置
  3. quicktype-core で 配置した JSON を JSON Schema に変換
  4. JSON Schema を Open API のcomponents.schemas.{スキーマ}に変換
  5. requestBody、responsesの$refが、生成したスキーマを参照するpathsも生成
  6. Open API のinfoやserversはテンプレートのJSONに書いておく
  7. テンプレートの JSON にpathsとcomponents.schemas.{スキーマ}を入れてファイル化

仕組みの開発に着手してから1日でやったことです。4と5のステップを開発するのに80%ぐらいの時間を掛けました。

今の不満はブラウザーコンソールでリクエスト／レスポンスのJSONを取得してファイルとして配置する作業が手動ということです。そしてお風呂で考えました。

Chrome拡張からネットワークの見てOpen APIを生成できないかな？？

chrome.devtools.network

はい、前行きが長くなりましたがこの記事ではOpen APIを生成するChrome拡張を妄想してみます。
Open API の生成が目的なので、SSRしているアプリはこのツールの対象外です。

Chrome拡張からHARを参照する

やりたい度: ⭐️⭐️⭐️⭐️⭐️

やりたいというか、これがないと始まらないですね。

Chrome拡張ならHARを参照できます。HARには Open API を生成させるための情報は全部入っていると考えていいでしょう。もちろんsummary、descriptionのような設計者に聞いてみないと分からない項目は除きます。

次のコードで動きそうです。

chrome.devtools.network.onRequestFinished.addListener(
  (request) => {
    // request にコンソールのネットワークパネルで見れる情報が全部入っている
  }
);

chrome.devtools.network.onRequestFinished.addListener(
  () => {
    chrome.devtools.network.getHAR((har) => {
      // イベントが発生するたびにHARを取得することもできる
    });
  }
);

[追記] zenn.dev の HAR を覗いてみた

試しに zenn.dev の HAR を覗いてみました。HARって、何を記録したのか分からないデータがたくさん詰まっていますが、この記事を更新したデータは次のようなアウトラインです。

『読める、読めるぞ』

Chrome拡張なら Open API を Swagger UI で表示できる

やりたい度: ⭐️⭐️⭐️⭐️⭐️

ぽちぽちサイトを操作してサイトからサーバーへのリクエスト／レスポンスの情報をツールに溜めていきます。

どれぐらい溜まっているのか JSON or YAML をダウンロードしないと中身が確認できないのでは使い勝手が悪いですね。そこで Swagger UI を使ってコンソールの開発者パネルに表示しちゃいましょう。

私は関数型プログラミング信者なので、次のような関数を作ります。

const openApi = createOpenApiFromHAR(har);

それをReactでレンダリングしちゃいます。

import SwaggerUI from "swagger-ui-react"
import "swagger-ui-react/swagger-ui.css"

const openApiJson = JSON.stringify(openApi);
export default App = () => <SwaggerUI spec={openApiJson} />

https://www.npmjs.com/package/swagger-ui-react

新しいリクエストを飛ばしたらスナックバーで通知したい

やりたい度: ⭐️⭐️⭐️⭐️⭐️

それなりに機能がたくさんあるアプリならリクエストの種類も多いでしょう。Swagger UI をリアルタイムに更新しても、スクロールしないと見えない領域に表示されていたら Open API が更新されたことに気がつきません。

新しいパス(URL, Method)にリクエストを飛ばしたらスナックバーで通知したいですね。
また現在のpathsに表示するパスの本数は固定領域に常に表示させておきたいですね。

過去に生成した Open API のダウンロード

やりたい度: ⭐️

chrome.storageに生成した Open API を保存しておけば、あとからダウンロードできると便利かも？
でもchrome.storageにはセキュリティーに影響のあるデータを格納したくない。セキュリティー関係する話になると大変になりますよね。皆様もHARファイルの扱いには慎重に。

過去のHARをマージして　Open API　を　生成する

やりたい度: ⭐️⭐️⭐️

ツール側でセキュリティー上の課題を抱えたくないので、HARをダウンロードして管理してもらうとしましょう。
その過去のHARを複数選択するとそれらを連続したイベントデータとして　Open　API　を生成します。

レアなリクエストがあるとしましょう。例えば、そのリクエストを発生させないとenumのスキーマが十分な定義にならないケースとかありそうですよね。

そういった場合にHARを取っておいていつでもマージできると便利そうです。

まとめ

const openApi = createOpenApiFromHAR(har, options);

この関数の開発は大変そうです。
Chrome拡張の開発は1年ぐらい専念していた経験があるので、開発者パネルの開発だけなら簡単そうです。
以前はWebpackでビルドしていましたが、このツール開発にトライするならViteでやってみたいですね。

やってみみますか。

Discussion