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/

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開発」という内容で登壇予定
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
25. めっちゃ簡単にモックできた😆

27. コレジャナイ感
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. 
 ご静聴ありがとうございました