Upgrade to Pro — share decks privately, control downloads, hide ads and more …

OpenAPIを使ってAPIドキュメントとモックサーバーを良い感じにした話

 OpenAPIを使ってAPIドキュメントとモックサーバーを良い感じにした話

2021年6月2日に行われたSendai Frontend Meetup #6で使用したスライドです。

GitHub サンプルコード
https://github.com/KanDai/openapi-sample

ReDocで生成されたドキュメント
https://kandai.github.io/openapi-sample/

About Swagger Specification
https://swagger.io/docs/specification/about/

Swagger Editor
https://editor.swagger.io/

Stoplight Studio
https://stoplight.io/api-design/

Swagger UI
https://petstore.swagger.io/

Redoc
https://github.com/Redocly/redoc

Prism
https://stoplight.io/open-source/prism/

Daichi

June 02, 2021
Tweet

More Decks by Daichi

Other Decks in Technology

Transcript

  1. 2021.06.02 @ Sendai Frontend Meetup #6 オンライン
    株式会社TAM 菅家大地
    OpenAPIを使って
    APIドキュメントとモックサーバーを
    良い感じにした話

    View Slide

  2. 株式会社TAM フロントエンドエンジニア
    菅家 大地 / Daichi Kanke
    元デザイナーのフロントエンドエンジニア
    福島→宮城→東京→宮城
    PWA Night / 仙台フロントエンドUG
    Vue.js / Nuxt.js / PWA / Monaca
    daichi.kanke
    @kan_dai

    View Slide

  3. 「サンプルを通して学ぶPWA開発」という内容で登壇予定

    View Slide

  4. View Slide

  5. APIのドキュメント
    何で作ってますか?

    View Slide

  6. ● Excel
    ● Google Spreadsheet
    ● Word
    ● wiki (markdown)
    ● ドキュメントなんて無い

    View Slide

  7. ● Excel
    ● Google Spreadsheet
    ● Word
    ● wiki (markdown)
    ● ドキュメントなんて無い
    個人的に思っていたこと
    編集しづらい
    最新ファイルこれだっけ?
    どこが変わったんだ?

    View Slide

  8. https://swagger.io/docs/specification/about/

    View Slide

  9. ● OpenAPIはREST APIを記述するためのフォーマット
    ● YAMLまたはJSONで記述する
    ● API開発に便利なツールを使うことができる
    ○ ドキュメント生成
    ○ モックサーバーやクライアントライブラリ生成
    ○ 自動テスト
    ○ TypeScriptの型定義を生成

    View Slide

  10. ● OpenAPIはREST APIを記述するためのフォーマット
    ● YAMLまたはJSONで記述する
    ● API開発に便利なツールを使うことができる
    ○ ドキュメント生成
    ○ モックサーバーやクライアントライブラリ生成
    ○ 自動テスト
    ○ TypeScriptの型定義を生成

    View Slide

  11. ● ドキュメント生成
    ○ 編集しづらいことが多かったので改善したかった
    ○ アップデートのたびに配布したりするのが大変
    ○ 編集履歴がわかりづらい
    ● OpenAPI定義ファイルをもとにモックサーバー立ち上げ
    ○ APIの開発が終わってなくてもフロントの開発を進めたい
    ○ 仕様書からモック用のプログラムを書いたりしていた

    View Slide

  12. API仕様を書く


    View Slide

  13. https://editor.swagger.io/

    View Slide

  14. つらい😩


    View Slide

  15. https://stoplight.io/api-design/

    View Slide

  16. アプリケーションダウンロードして使ってます

    View Slide

  17. ドキュメントの生成


    View Slide

  18. https://petstore.swagger.io/

    View Slide

  19. https://github.com/Redocly/redoc

    View Slide

  20. $ redoc-cli bundle sample.json
    HTMLにタグを入れるだけでOK
    CLIツールから1ファイルにバンドルされたHTMLを生成できる
    HTML生成してプロジェクト管理ツールに置いて見れるようにした

    View Slide

  21. モックサーバー立ち上げ


    View Slide

  22. https://stoplight.io/open-source/prism/

    View Slide

  23. ● OpenAPI定義ファイルからモックサーバーを立ち上げてくれる
    ● Stoplight Studioにも組み込まれている
    ○ 一人で使う分にはそれだけでも良いが、チームで使う場合に全員に
    アプリをインストールしてもらうのは微妙・・・
    ● nodeモジュールでprism-cliが提供されているので、それがオススメ
    (dockerもある)
    ● 値を毎回動的に変えてくれるオプションなどもある
    Prism

    View Slide

  24. View Slide

  25. めっちゃ簡単にモックできた😆


    View Slide

  26. View Slide

  27. コレジャナイ感

    View Slide

  28. View Slide

  29. リクエストヘッダーに `Prefer: example=example-5` のように付与することで特定の
    レスポンス例を返すことができる。
    モックでもパラメーターによってレスポンスを変更したい場合などに便利。

    View Slide

  30. ● `--cors=false` オプションを発見するもダメだった
    ● Access-Control-Allow-Origin の default に * を入れたらいけた
    案の定CORS問題

    View Slide

  31. ● レスポンスを少し遅らせたい
    ○ 実際に起こるレスポンスまでのラグが再現できない
    ○ ローディングのUIの確認とかしにくい
    ○ 今はローカルの時だけsetTimeoutを入れたりしている
    ● スマホの実機チェックする時にAPIは繋がらない
    ● 誰か良い方法あれば教えてください
    まだ解決してない問題

    View Slide

  32. ● ドキュメント作成とモックサーバーの作成をまとめられたので
    普通に良かった
    ● OpenAPIとその周辺ツールを活用していくことで、APIに関
    するなんやかんやを楽にできそう
    まとめというか感想

    View Slide

  33. GitHub サンプルコード
    https://github.com/KanDai/openapi-sample
    ReDocで生成されたドキュメント
    https://kandai.github.io/openapi-sample/

    View Slide


  34. ご静聴ありがとうございました


    View Slide