【Reactで！】OpenAPIをブラウザで表示する方法についてご紹介！

こんにちは！エンジニアの橋本です！

現在ノベルティでも推奨しているサイト構築方法、Jamstack。こちらは静的なサイトを事前に生成し、必要に応じてAPI経由でデータを取得・表示するという方法を取ります。

そんなJamstackに欠かせない要素...API！

そのAPIを定義するためのツールにはさまざまありますが、その中でも人気のOpenAPIというものがあります。

OpenAPIについて取り扱うコラムは多々ありますが、今回はOpenAPIで定義した情報をWeb上に公開する方法についてご紹介させていただこうと思います！

OpenAPIとは

OpenAPI(以前はSwaggerとも呼ばれていました）は、REST APIの設計や構築そしてドキュメント化を支えるフレームワークです。

具体的にはAPIがどのように動作すべきかを記述するために利用します。これは決してJamstack専用という形ではなく、言語に依存しません。PHPでもJavascriptでもPythonでも、この定義書を利用することができます。

ここでポイントなのが、通常のドキュメントと異なりOpenAPIは実際にテストすることができます。

パラメータやレスポンスメッセージの設定、認証方法はどのような方法か...定義することでフロントエンドとバックエンドの実装の齟齬を無くします。

フロントエンド側もバックエンド側もお互いの機能実装前にテストができるので、API駆動設計にはなくてはならない存在って感じですね。忘れた頃に行う保守でもかなり活躍してくれるはずです。

Reactで実践

まず、前提としてOpenAPIはyamlという形式のファイルで作成します。

このファイルをWebブラウザ上に公開しても、人間にとって視認性のある形にもできませんし、テストなどの必要機能も実装できません。

そこで今回はReactを通じてWebブラウザ上に公開する方法を取ります。

もちろんお調べいただければ、その他の方法でも公開することが可能です。ご自身の知っている言語で構成できるので、これがOpenAPIの良さですね！

下準備

まずは下準備、React環境を用意します。これはデフォルトの環境で問題ありません。

必要なファイルはindex.jsだけなので、その他不要なファイルは削除しても問題ありません。

諸々プロジェクトによって拡張したいと思うので、その点は臨機応変に追加していきましょう。

ライブラリ解説

今回は最も簡単な方法をご紹介させていただきたいので、ステップ数は少なめです。

まずは下記のライブラリをインストールします。

これでSwaggerの準備はOKです！

npm install swagger-ui-react

次に、src下のindex.jsを下記のように編集しましょう。

import React from "react";

import ReactDOM from "react-dom/client";

import SwaggerUI from "swagger-ui-react";

import "swagger-ui-react/swagger-ui.css";

const root = ReactDOM.createRoot(document.getElementById("root"));

root.render(<SwaggerUI url="openapi.yaml" />);

肝心のOpenAPI定義書である「openapi.yaml」は、publicフォルダ配下に置きます。

これで下記のアクセス方法でSwaggerのUIを展開することが可能になります。

root.render(<SwaggerUI url="openapi.yaml" />);

ここまでできたら下記コマンドでローカルサーバーを立ち上げ、実際の画面を確認してみましょう。

npm run start

これでご自身が定義したOpenAPI定義書の内容が正しく表示されていることをできたら、最後に下記コマンドでWebブラウザに展開できるようにします。

npm run build

これでbuild配下のファイルを指定のWebサーバーにアップロードすることで完了です！

もちろん各種ホスティングサービスやgitActionなどと連携することでgitプッシュ時に展開することも可能です。

普段Reactを取り扱っているやり方でWeb展開いただければと思います。

Swagger Editorの活用も！

上記のようにローカル環境で管理できれば柔軟性はありますが、お手軽な方法としては「Swagger Editor」というツールを利用する方法もあります。

こちらは公式から提供されているツールで、お手軽にブラウザ上でリアルタイム編集が可能です。

ローカル環境にダウンロードもできるので、まずは個人開発で何か定義したいなどのケースでは、最初はこちらを使ってみるのも良いかもしれません！

その他の閲覧方法もあり！

上記のようにWebブラウザで閲覧する以外にも、お手軽にローカル環境でSwaggerのUIを実現することも可能です！

これにはVSCodeが必要になりますが、とても簡単。「Swagger Viewer」というプラグインを利用します。

インストールさえすれば、yamlファイルを開いている状態で「Shift + Alt + P」→「Preview Swagger」の入力でSwaggerのUIを確認することができますよ！

まとめ

今回はOpenAPIをWeb公開する方法を中心にご紹介させていただきました！

元々がかなり便利なOpenAPIですが、これで第三者への共有がより便利になりますね。

ノベルティではこのようにモダンフロントエンド開発／制作を得意としております！

パフォーマンスやセキュリティに優れたサイト制作を希望されている方はぜひ一度ご相談ください。

お問い合わせはこちらから！

それではまた！