All rights reserved by Postman Inc VS CodeとPostmanを活用 した効率的なAPI開発 〜 API開発も生成AIの賜物 〜 川崎庸市 Postman株式会社 Presentation slides for VS Code Meetup #26

Technology Evangelist Postman株式会社 川崎 庸市 / Yoichi Kawasaki @yokawasa @postman_japan

アジェンダ ● APIファースト開発モデル概要 ● VS Code x Postman活用したAPI開発デモ

APIファースト開発モデル概要

APIファーストの世界 https://api-first-world.com/ja/

APIファーストとは？ ● APIに対する位置づけ、考え方 ○ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ○ APIがビジネスにもたらす価値に焦点を当てる ○ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 ● APIファースト採用のために必要な取り組み ○ APIライフサイクルを理解しライフサイクル全体で取り組む ○ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/

APIはプロダクト = 第一級市民 ● APIは後付で構築するものではなく、最優先で構築するもの ● 戦略的なビジネスアセットとしてライフサイクル全体で管理する ● 一回きりのプロジェクトではなく、継続的に管理する ● 継続的な保守・運用のためのチーム体制を構築する

Planning Defining Designing Building Testing Deployment SDLC (Software Development Life Cycle)

API提供者と利用者のAPI開発ライフサイクル

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開発環境

コードを書く前にAPIを設計・構築するとは？ 要件 API設計 コード API Spec作成 APIドキュメント作成 モック作成 テストコード作成 API定義・生成 テスト モック、テスト結果を元にレビューや フィードバックを受け設計内容を洗練させ る作業を繰り返す

デザイン、モック作、フィードバックループ API Spec API Documentation Mocks Tests Code Stubs Client SDK Defining & Designing Building Testing Deployment Monitoring & Observing Existing Code

２つのAPI開発モデルを比較 要件 要件 コード API設計 API Docs / Tests コード Comment Annotation API Spec API Docs API Mock API Tests コードファースト APIファースト

コードファースト開発モデル 要件 コード API Docs / Tests ポイント ● 要件を元にAPI実装後にAPIテスト・ドキュメント作成。 ● 焦点はAPI (インターフェース) ではなくコア機能。APIは後付 け。APIを実装する段階になるとコア機能はほぼ完了 メリット - 迅速なプロトタイピング - 柔軟性と適応力。要件の変更や市場の変化に迅速に対応 デメリット - API内容がコア機能や利用テクノロジーに引っ張られやすい - APIドキュメントや結合テストが後付けになるため、品質リスクや途中開発 における関係者間のコラボレーションへの弊害 - 仕様確定やテスト実施によるフィードバックが開発プロセス後半になるた め、問題がある場合の変更コストが大きい

APIファースト開発モデル ポイント ● APIコードを書く前にAPIを設計・構築 ● API設計フェーズでフィードバックループを通じて設計内容を洗 練化 メリット ● 設計品質、開発者エクスペリエンス向上 ● 要件・設計などの問題について早期発見ができ、変更コストが低いうちに変 更、方向転換ができる。不確実性に対して柔軟。 ● 設計段階で、APIドキュメントやテスト生成され、比較的初期段階でも関係 者間でコラボレーションが可能 デメリット ● 設計フェーズに時間がかかる ● 要件の変更に対する対応に時間がかかりがち（設計から入るため） 要件 コード API設計

実はAPI開発 かなりの部分が自動生成できます

API 仕様からのドキュメント、モック、テスト生成 OpenAPI ツール群 https://tools.openapis.org/ 例えば次のようなツールを使えばかなりの部分の自動生成を実現できます Postman https://postman.com

本日のお題 VS Code x Postmanを活用した API開発デモ デモフロー詳細とサンプル https://gist.github.com/yokawasa/fbc0230343bbf1af5bac49855304aff9

スコープはこの部分 API設計 テスト APIドキュメント 作成 モック作成 実装 コーディング 統合 テスト実行 監視実行 サーバー環境 Dev Stage Prod モック活用 テスト ドキュメント 活用 コードリポジトリ モックを元にレビューや フィードバックを受け 設計内容を洗練させる check-in デプロイ エンドポイント にテスト API開発環境

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

利用するツール・機能

VS Code extension: GitHub Copilot Chat https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat OpenAPI Specの生成に活用

VS Code extension: OpenAPI (Swagger) Editor https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi OpenAPI Specのビュアー、デバック用に活用

VS Code extension: Postman https://marketplace.visualstudio.com/items?itemName=Postman.postman-for-vscode

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設計

Postman: モックサーバー - モック用サービス 実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成さ れ専用URLが発行される（デフォルトパブリックでプライベート設定可能） 。API 実装との依存関係が分離され、 他のチームの作業から独立して作業を進めることができる Service A Service B Service C API 未完成 依存 箇所 依存 箇所 モック サーバー @postman_japan モックテスト

Postman: Postbot - 生成AIを活用したテストコード生成 https://blog.postman.com/meet-postbot-postmans-new-ai-assistant/ テスト

Postman: コレクションランナー - 複数リクエストのテスト実行 実行 実行結果詳細表示 サマリー結果表示 順番入れ替え可能 実行方法選択 手動 / スケジュール実行 イテレーション数 遅延秒数 データファイル 指定可能 選択 コレクションメニュー コレクションランナー実行方法設定 テスト

本セッションではAPIファースト開発モデルの概要と その実践としてVS CodeとPostmanを活用したAPI開発方法をデ モを使って紹介させていただきました。 今後のAPI開発の参考になりましたら幸いです。

ご清聴いただき、ありがとうございました。