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

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

Daichi
June 02, 2021

 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ドキュメントとモックサーバーを 良い感じにした話
  2. 株式会社TAM フロントエンドエンジニア 菅家 大地 / Daichi Kanke 元デザイナーのフロントエンドエンジニア 福島→宮城→東京→宮城 PWA

    Night / 仙台フロントエンドUG Vue.js / Nuxt.js / PWA / Monaca daichi.kanke @kan_dai
  3. 「サンプルを通して学ぶPWA開発」という内容で登壇予定

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

  6. • Excel • Google Spreadsheet • Word • wiki (markdown)

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

    • ドキュメントなんて無い 個人的に思っていたこと 編集しづらい 最新ファイルこれだっけ? どこが変わったんだ?
  8. https://swagger.io/docs/specification/about/

  9. • OpenAPIはREST APIを記述するためのフォーマット • YAMLまたはJSONで記述する • API開発に便利なツールを使うことができる ◦ ドキュメント生成 ◦

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

    モックサーバーやクライアントライブラリ生成 ◦ 自動テスト ◦ TypeScriptの型定義を生成
  11. • ドキュメント生成 ◦ 編集しづらいことが多かったので改善したかった ◦ アップデートのたびに配布したりするのが大変 ◦ 編集履歴がわかりづらい • OpenAPI定義ファイルをもとにモックサーバー立ち上げ

    ◦ APIの開発が終わってなくてもフロントの開発を進めたい ◦ 仕様書からモック用のプログラムを書いたりしていた
  12. API仕様を書く


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

  14. つらい😩


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

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

  17. ドキュメントの生成


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

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

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

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


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

  23. • OpenAPI定義ファイルからモックサーバーを立ち上げてくれる • Stoplight Studioにも組み込まれている ◦ 一人で使う分にはそれだけでも良いが、チームで使う場合に全員に アプリをインストールしてもらうのは微妙・・・ • nodeモジュールでprism-cliが提供されているので、それがオススメ

    (dockerもある) • 値を毎回動的に変えてくれるオプションなどもある Prism
  24. None
  25. めっちゃ簡単にモックできた😆


  26. None
  27. コレジャナイ感

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

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

    案の定CORS問題
  31. • レスポンスを少し遅らせたい ◦ 実際に起こるレスポンスまでのラグが再現できない ◦ ローディングのUIの確認とかしにくい ◦ 今はローカルの時だけsetTimeoutを入れたりしている • スマホの実機チェックする時にAPIは繋がらない

    • 誰か良い方法あれば教えてください まだ解決してない問題
  32. • ドキュメント作成とモックサーバーの作成をまとめられたので 普通に良かった • OpenAPIとその周辺ツールを活用していくことで、APIに関 するなんやかんやを楽にできそう まとめというか感想

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

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