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ドキュメントとモックサーバーを
   良い感じにした話
   

   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