Efficient API development using Postman, VS Code, and Generative AI

README.md

Developing TODO API using Postman, VS Code, and Generative AI

Todo appのためのAPIを開発する

Procedure

1. GitHub Copilot / ChatGPTにpromptで要件をインプットしTodo app用のOpen API Spec（以下OAS）を作ってもらう

• VS Code extension GitHub Copilot Chat
• VS Code extension OpenAPI(Swagger) Editor

2. Postman API BuilderにAPI定義としてOASファイルをインポートし、定義を元にPostmanコレクションを生成

• 生成されたコレクションの内容をチェック
• 必要に応じてPostmanコレクションのexampleデータをただしく調整する
• 生成されたコレクションをCollectionsにコピー、またはFork

3. MockServerを生成し、2で生成されたコレクションをMock APIとして動作確認可能にする

• 2で生成されたコレクションをMockServerに関連付ける
• コレクション変数{{baseUrl}}にMockServerのエンドポイントを設定
• 各APIの動作確認 using The Postman VS Code extension

4. Postbotを活用して各APIのテストを自動生成

• Postbotでテスト自動生成
• 各APIのテスト実行 using The Postman VS Code extension
• コレクションランナーからまとめてテスト実行 using The Postman VS Code extension

5. サンプルのフロントエンドアプリと3で設定したMockAPIで結合テスト

• フロントエンドアプリのAPI接続箇所をMockAPIに向ける
• 動作確認

6. おまけ: Postbotを活用してAPIドキュメントの記述文書自動生成

サンプルprompt

TODOアプリのためのAPIをつくりたい。そのOpen API Specを作ってください。
各APIの定義にはリクエストとレスポンスのexamplesを追加してください。出力形式はYAML

###条件
このアプリには以下の機能が含まれます

- TODO項目の作成：新しいTODOを追加する。追加時はTODOのタスク名だけを与える
- TODO項目のリスト表示：全てのTODO項目を表示する
- TODO項目の更新：既存のTODO項目をIDを元に更新する
- TODO項目の削除：特定のTODO項目をIDを元に削除する

TODOのデータ構造は次のプロパティを持ちます

- id: TODOのID。文字列型
- task:  TODOのタスク名。文字列型
- completed: TODOが完了したかどうかを表すフラグ。ブーリアン型

GitHub Copilot Chat出力結果

opneapi.yaml

openapi: 3.0.0
info:
  title: TODO Application API
  version: 1.0.0
paths:
  /todos:
    get:
      summary: Get a list of all TODO items
      responses:
        '200':
          description: A list of TODO items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Todo'
              examples:
                todoListExample:
                  value:
                    - id: "1"
                      task: "Buy groceries"
                      completed: false
                    - id: "2"
                      task: "Read a book"
                      completed: true
    post:
      summary: Create a new TODO item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TodoCreate'
            examples:
              todoCreateExample:
                value:
                  task: "Do homework"
      responses:
        '201':
          description: Created TODO item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Todo'
              examples:
                todoExample:
                  value:
                    id: "3"
                    task: "Do homework"
                    completed: false
  /todos/{id}:
    put:
      summary: Update a TODO item
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TodoUpdate'
            examples:
              todoUpdateExample:
                value:
                  completed: true
      responses:
        '200':
          description: Updated TODO item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Todo'
              examples:
                todoExample:
                  value:
                    id: "1"
                    task: "Buy groceries"
                    completed: true
    delete:
      summary: Delete a TODO item
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted TODO item
components:
  schemas:
    Todo:
      type: object
      properties:
        id:
          type: string
        task:
          type: string
        completed:
          type: boolean
    TodoCreate:
      type: object
      properties:
        task:
          type: string
    TodoUpdate:
      type: object
      properties:
        completed:
          type: boolean

Relevant materials: Presentation slides