VS CodeとPostmanを活用した効率的なAPI開発 / Efficient API development using VS Code and Postman

Presentation Slides for VS Code Meetup #26 - with Postman! @LODGE
Session title: VS CodeとPostmanを活用した効率的なAPI開発 / Efficient API development using VS Code and Postman
Date: 2023/11/28

Transcript

1. All rights reserved by Postman Inc VS CodeとPostmanを活用 した効率的なAPI開発 〜 API開発も生成AIの賜物 〜 川崎庸市 Postman株式会社 Presentation slides for VS Code Meetup #26
2. Technology Evangelist Postman株式会社 川崎 庸市 / Yoichi Kawasaki @yokawasa @postman_japan
3. アジェンダ • APIファースト開発モデル概要 • VS Code x Postman活用したAPI開発デモ
4. APIファースト開発モデル概要
5. APIファーストの世界 https://api-first-world.com/ja/
6. APIファーストとは？ • APIに対する位置づけ、考え方 ◦ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/
7. APIはプロダクト = 第一級市民 • APIは後付で構築するものではなく、最優先で構築するもの • 戦略的なビジネスアセットとしてライフサイクル全体で管理する • 一回きりのプロジェクトではなく、継続的に管理する • 継続的な保守・運用のためのチーム体制を構築する
8. Planning Defining Designing Building Testing Deployment SDLC (Software Development Life Cycle)
9. API提供者と利用者のAPI開発ライフサイクル
10. APIファースト開発モデル • 焦点はAPIの設計（システムの抽象的な「契約」） • コードを書く前にAPIを設計・構築し、モック、ドキュメント、テストも作成 • 設計フェーズでフィードバックループを通じて設計内容を洗練化 API-first software development for modern organizations　 https://medium.com/better-practices/api-first-software-development-for-modern-organizations-fdbfba9a66d3 API設計 テスト APIドキュメント 作成 モック作成 実装 コーディング 統合 テスト実行 監視実行 サーバー環境 Dev Stage Prod モック活用 テスト ドキュメント 活用 コードリポジトリ モックを元にレビューや フィードバックを受け 設計内容を洗練させる check-in デプロイ エンドポイント にテスト API開発環境
11. コードを書く前にAPIを設計・構築するとは？ 要件 API設計 コード API Spec作成 APIドキュメント作成 モック作成 テストコード作成 API定義・生成 テスト モック、テスト結果を元にレビューや フィードバックを受け設計内容を洗練させ る作業を繰り返す
12. デザイン、モック作、フィードバックループ API Spec API Documentation Mocks Tests Code Stubs Client SDK Defining & Designing Building Testing Deployment Monitoring & Observing Existing Code
13. ２つのAPI開発モデルを比較 要件 要件 コード API設計 API Docs / Tests コード Comment Annotation API Spec API Docs API Mock API Tests コードファースト APIファースト
14. コードファースト開発モデル 要件 コード API Docs / Tests ポイント • 要件を元にAPI実装後にAPIテスト・ドキュメント作成。 • 焦点はAPI (インターフェース) ではなくコア機能。APIは後付 け。APIを実装する段階になるとコア機能はほぼ完了 メリット - 迅速なプロトタイピング - 柔軟性と適応力。要件の変更や市場の変化に迅速に対応 デメリット - API内容がコア機能や利用テクノロジーに引っ張られやすい - APIドキュメントや結合テストが後付けになるため、品質リスクや途中開発 における関係者間のコラボレーションへの弊害 - 仕様確定やテスト実施によるフィードバックが開発プロセス後半になるた め、問題がある場合の変更コストが大きい
15. APIファースト開発モデル ポイント • APIコードを書く前にAPIを設計・構築 • API設計フェーズでフィードバックループを通じて設計内容を洗 練化 メリット • 設計品質、開発者エクスペリエンス向上 • 要件・設計などの問題について早期発見ができ、変更コストが低いうちに変 更、方向転換ができる。不確実性に対して柔軟。 • 設計段階で、APIドキュメントやテスト生成され、比較的初期段階でも関係 者間でコラボレーションが可能 デメリット • 設計フェーズに時間がかかる • 要件の変更に対する対応に時間がかかりがち（設計から入るため） 要件 コード API設計
16. 実はAPI開発 かなりの部分が自動生成できます
17. API 仕様からのドキュメント、モック、テスト生成 OpenAPI ツール群 https://tools.openapis.org/ 例えば次のようなツールを使えばかなりの部分の自動生成を実現できます Postman https://postman.com
18. 本日のお題 VS Code x Postmanを活用した API開発デモ デモフロー詳細とサンプル https://gist.github.com/yokawasa/fbc0230343bbf1af5bac49855304aff9
19. スコープはこの部分 API設計 テスト APIドキュメント 作成 モック作成 実装 コーディング 統合 テスト実行 監視実行 サーバー環境 Dev Stage Prod モック活用 テスト ドキュメント 活用 コードリポジトリ モックを元にレビューや フィードバックを受け 設計内容を洗練させる check-in デプロイ エンドポイント にテスト API開発環境
20. API開発デモフロー API設計 APIドキュメント テスト作成 モックAPI 作成 テスト実行 • GitHub Copilot Chatで prompt入力しOpenAPI Sepc (OAS)を作成 • 作成されたOASを Postmanにインポートし、 コレクションを生成 • モックサーバ作成 • モックAPIを作成（モック データはOASのexampleを ベース） • モックAPIの動作確認 • コレクションランナー でまとめてテスト実行 • Postbotでテストコード 自動生成 結合テスト • サンプルフロントアプ リとモックAPIを結合 ① ② ③ ④ ⑤ デモフロー詳細とサンプル https://gist.github.com/yokawasa/fbc0230343bbf1af5bac49855304aff9
21. 利用するツール・機能
22. VS Code extension: GitHub Copilot Chat https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat OpenAPI Specの生成に活用
23. VS Code extension: OpenAPI (Swagger) Editor https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi OpenAPI Specのビュアー、デバック用に活用
24. VS Code extension: Postman https://marketplace.visualstudio.com/items?itemName=Postman.postman-for-vscode
25. Postman: API設計支援ツール - APIビルダー OpenAPI Postman Collection RAML WSDL GraphQL ProtoBuf チームによるAPI設計を支援するツールです。直感的なUIを介してAPIの構造を定義できます APIビルダーの主要機能 • API設計 ◦ スキーマ定義（インポートも可能） ◦ API定義のバリデーション ◦ 定義からサーバーコード生成 ◦ テスト、ドキュメント生成 ◦ コレクション生成 • チーム開発支援 ◦ チーム間のAPI共有 ◦ コメント、Changelog • APIバージョン管理 ◦ コードリポジトリ(GitHub, GitLab, Bitbucket, and Azure)と同期 API設計
26. Postman: モックサーバー - モック用サービス 実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成さ れ専用URLが発行される（デフォルトパブリックでプライベート設定可能） 。API 実装との依存関係が分離され、 他のチームの作業から独立して作業を進めることができる Service A Service B Service C API 未完成 依存 箇所 依存 箇所 モック サーバー @postman_japan モックテスト
27. Postman: Postbot - 生成AIを活用したテストコード生成 https://blog.postman.com/meet-postbot-postmans-new-ai-assistant/ テスト
28. Postman: コレクションランナー - 複数リクエストのテスト実行 実行 実行結果詳細表示 サマリー結果表示 順番入れ替え可能 実行方法選択 手動 / スケジュール実行 イテレーション数 遅延秒数 データファイル 指定可能 選択 コレクションメニュー コレクションランナー実行方法設定 テスト
29. 本セッションではAPIファースト開発モデルの概要と その実践としてVS CodeとPostmanを活用したAPI開発方法をデ モを使って紹介させていただきました。 今後のAPI開発の参考になりましたら幸いです。
30. ご清聴いただき、ありがとうございました。