フロントエンド開発のためにモックサーバーを使いたかった
フロントエンドのAPI実装をするにあたって、モックサーバーを作るためのツールを検索していたら、API仕様書作成ツールのSwaggerのサードパーティ製ライブラリのSwagger Studioで作成した仕様書のモックサーバーを簡単に利用できることを知った。
元々モックサーバー用のライブラリであるPrismが統合されているらしい。
GUIで直感的にAPI定義できる
SwaggerではAPI仕様書をyamlファイルを書いて作成していくが、Swagger Studioを利用するとGUIで直感的に操作して定義を作成しそのコードを出力することができる。
実際に操作してみる
まずアカウントを作成ます。
API Design & Documentation Management | Designing & Building OpenAPIs
自分のワークスペースを作成したらプラスアイコンから新規プロジェクトを立ち上げる。
今回はSampleAPIという名前で作成。
左上のプラスアイコンからメニューを開きAPIを選んで、APIを作成していく。
途中プレビューを押すと仕様書のフォーマットで確認することができる。
Modelを作成する
上記と同じプラスアイコンからModelを選んで作成します。
GUIで直感的に定義していくことができます。
今回はオブジェクトの配列を返すAPIを定義しました。オブジェクトの中身はnumber型とstring型で定義します。
Responseを作成
プロジェクト作成時にデフォルトでエンドポイントが作成されているのですが、それを編集しました。エンドポイントのURLも自分の好きなものに変えられます。
今回試しにGetAPIのみ作成するので、GetでResponseを作っていきます。
Schemaで$refを選び、targetに先ほど作成したModelをプルダウンで選びます。
モックサーバーで取得できるexmpleを入れておきます。
デフォルトのものは削除して、下記のようなデータを作りました。
全体の確認とコードの修正
全体的にみるとこんな感じです。
今回sampleなのでHeaderなどは入れてませんが、その辺も簡単に追加できそうです。
プレビューを押すと、仕様書の見た目で確認できます。
実際作成する仕様書はRedocを使いますので下記の見た目とは違いますが、内容の確認で使えます。
プレビュー隣に警告がでている場合、警告の箇所をクリックすると、警告箇所のコードに飛ぶことができるので、そこを手修正します。
下記ではわざとヒトカゲのコメントの箇所にエラーを出しましたが、直すと警告が消えています。
モックサーバーを利用して動作を確認する
GetAPIの定義が完成しましたので早速モックサーバーでAPIを取得してみます。
先ほどのプロジェクトで作ったAPIをPublishするとワークスペースで作成したAPIが確認できるようになります。
すでにBaseURLでLive serverとMock serverの記載があります。
APIの詳細を表示すると、なんと右側に取得するコードと結果sampleが。
sampleコードはいろんな言語に切り替えることもできます。
めっちゃ楽ですねぇ。。。
Mock serverを選択してSend API Reqesutを押すとMock serverからResponseが帰ってきていることが確認できます。
Code sand boxで試しにAPI叩いても問題なく取得できました。
API仕様書をHTML形式で保存する
作ったAPIの仕様書をHTMLの形式で共有しやすいように保存します。
ワークスペースの下記画面のエクポートでyamlのコードを出力できるのでそれをコピーしておきます。
yamlファイルを作成する
ファイルはVScodeの拡張機能でOpenAPIEditorがあるので、それで作ったファイルにコピペして保存している。修正ある場合はEditorでの修正も可能。
プレビューで仕様書の内容もみることができます。
別にこれを使わなくても普通に新規のyamlファイルを作成してコピペでもできると思いますが、自分でコードを書いていくことになったときどのみち使うかもしれないので、インストールしました。
ファイルはわかりやすくOpenAPIというディレクトリを作ってそこに保存しました。
CLIでymlファイルをHTMLに変換
demo http://redocly.github.io/redoc/
HTMLの変換はRedocというツールを使って行います。
いろいろな機能があるようですが、CLIでコマンド叩くだけでyamlファイルをHTMLに変換してくれるということだったので、それを使います。
インストールしてHTMLを生成したいディレクトリ上で実行すれば、そのディレクトリ配下にHTMLファイルが生成さている。
$ npm install -g redoc-cli
$ redoc-cli bundle openapi.yaml
実際生成されたHTMLを開くとこんな感じのおしゃれな仕様書ができました。
さいごに
今回モックサーバーが必要だったので、そこから検索してSwaggerに行きつきましたが、APIの仕様書も作れるようになってよかったです。
しかも簡単。
実際複雑なAPIの構築にはまだまだ勉強必要そうですが、スピーディーにフロントの開発をするにはよいツールだなと思います。
参考にした記事
本当に使ってよかったOpenAPI (Swagger) ツール
https://future-architect.github.io/articles/20191008/
OpenAPI関連のサイト・ツールまとめ
https://gift-tech.co.jp/articles/round-up-openapi-tools/
SwaggerでRESTful APIの管理を楽にする
https://qiita.com/disc99/items/37228f5d687ad2969aa2
[Swagger] OpenAPI3.0で記述したAPI仕様書をHTMLとして出力する
https://qiita.com/godgarden/items/be420a8c165f4a0f3ad8
Stoplight Studio を試す
https://blog.takeyuweb.co.jp/entry/2020/05/11/000000
【Swagger】Swagger Spec (yaml) の書き方 〜GET編〜
https://qiita.com/oden141/items/8591f47d67dca09cc714
CLIでモックサーバー作成してる記事↓
【OpenAPI】Prismでモックサーバ作成 https://qiita.com/andynuma/items/bf043b5184d3826d0f92