👷

OpenAPIとMSWを使用しAPIレスポンスに対するStorybookを作成する

Hidetoshi Ota2022/08/22に公開

ファンタラクティブのエンジニアの 太田 です。
OpenAPIスキーマで定義したレスポンスに対するexampleをmswとstorybookでも使用してAPIスキーマで想定したレスポンスをStorybookで確認できるようにする試みについて紹介します。

https://www.openapis.org/
https://storybook.js.org/
https://github.com/mswjs/msw

やりたいこと

OpenAPIスキーマで定義したexamplesを参照してmswでAPIモックを定義、定義したAPIモックをstorybookで使用

嬉しいこと

APIで想定したレスポンスに対してフロントの挙動をStorybook上で確認できるのでAPIとフロントの認識のずれが改善されます。
エラーの表示や、権限によるUIの出し分けなど大変な確認を、APIスキーマで定義した内容を網羅する形でStorybook上で確認できます。
逆にAPIスキーマに定義されていないものはStoryを作らないので、確認するべきものはすべてAPIスキーマで定義しましょうということになります。

実装

※ 大雑把なコードでたぶん動きませんので参考までに

OpenAPIスキーマを定義する

https://github.com/052hide/oas_msw_storybook/blob/main/openapi.yml

今回はexamplesが重要なのでexamplesをしっかり定義しましょう。

openapi-examples-validator などのツールを使用してスキーマとexamplesの乖離がないことを確認するとよいかもしれません。

定義したexamplesをTypeScriptで参照できるようにするため、swagger-cliを使用してjsonに変換します。[1]

swagger-cli -r -t json -o ./openapi.json bundle ./openapi.yml

MSWを定義する

OpenAPIのexamplesを参照し、エンドポイント毎にモックを作ります。

https://github.com/052hide/oas_msw_storybook/blob/main/.mocks/handlers.ts

Storybookを定義する

定義したMSWのハンドラーを使用し、storyを作成します。

https://github.com/052hide/oas_msw_storybook/blob/main/components/SamplePage/SamplePage.stories.tsx

あとがき

Storybookでやれることが増えてきていてすごいなーと思いつつ、Story作るのなかなか大変ですね。
ページやAPIを呼ぶコンポーネントはAPIスキーマで定義したexamplesの関するStory、その他のコンポーネントで最大文字数などUIに関するstoryを作成するくらいがしっくりきています。

脚注
  1. jsonに変換しつつ$refをすべて展開したいのでyaml-loaderは使用せずswagger-cliを使用したjsonへの変換を好んでやっています ↩︎

Discussion

ログインするとコメントできます