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

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

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

Yoichi Kawasaki

November 28, 2023
Tweet

More Decks by Yoichi Kawasaki

Other Decks in Technology

Transcript

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  21. 利用するツール・機能

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide