API Development Skill

描述

API 開發流程引導技能，協助開發者選擇合適的開發流程（API First 或 Code First），並提供 OpenAPI 規格管理、程式碼產生等自動化支援。

職責

•引導選擇 API First 或 Code First 開發流程
•協助更新/建立 OpenAPI 規格（doc/openapi.yml）
•產生 Server Controller 骨架
•產生 Client SDK
•提供 Controller 實作指導

能力

1. 開發流程決策引導

協助開發者根據專案需求選擇合適的 API 開發流程：

•API First（推薦）：契約優先，文件與實作同步
•Code First：快速開發，後續維護文件

2. OpenAPI 規格管理

•檢查 doc/openapi.yml 是否存在
•引導新增/修改 API 端點定義
•提供 OpenAPI 3.0 規格範本
•驗證規格檔案格式

3. 程式碼自動產生

•Server Controller 產生：執行 task codegen-api-server
•Client SDK 產生：執行 task codegen-api-client
•產生位置自動化管理

4. Controller 實作協助

•提供 Controller 實作範本
•Result Pattern 整合指導
•HTTP 狀態碼映射建議

使用方式

在 GitHub Copilot 中使用

code

@workspace 我想要開發新的 API 端點

直接呼叫 Skill

code

使用 api-development 開發 API

互動流程

mermaid

graph TD
    A[啟動 Skill] --> B{詢問 API 開發流程}
    B -->|API First| C[檢查 OpenAPI 規格狀態]
    B -->|Code First| D[跳過規格，直接實作]
    C -->|已定義| E[提醒已存在定義]
    C -->|需更新| F[協助更新 OpenAPI 規格]
    C -->|尚未定義| G[協助建立 OpenAPI 規格]
    F --> H[執行 codegen-api-server]
    G --> H
    H --> I[產生 Controller 骨架]
    I --> J[提供 Controller 實作範本]
    J --> K[詢問是否產生 Client SDK]
    K -->|是| L[執行 codegen-api-client]
    K -->|否| M[完成]
    L --> M
    D --> N[提供 Code First 指導]
    N --> O[提醒後續需手動維護 OpenAPI]
    O --> M

互動問答範例

問題 1：API 開發流程選擇

code

請選擇 API 開發流程：

1️⃣ API First（推薦）
   ✅ API 文件與實作 100% 同步
   ✅ 前後端可並行開發
   ✅ 自動產生 Client SDK
   ✅ 編譯時契約檢查
   ⚠️ 需先設計 API 規格

   適用場景：
   - 前後端分離且團隊並行開發
   - 需要提供 Client SDK 給第三方
   - API 穩定性要求高
   - 多個客戶端（Web、Mobile、Desktop）

2️⃣ Code First
   ✅ 快速啟動開發
   ✅ 直接實作程式碼
   ⚠️ 需手動維護 API 文件
   ⚠️ 文件與實作可能不同步

   適用場景：
   - 快速原型驗證
   - 內部小型專案
   - API 結構仍在快速變動中
   - 單人開發或小團隊

問題 2：OpenAPI 規格定義狀態（僅 API First）

code

請確認 OpenAPI 規格狀態：

1️⃣ 已定義
   - doc/openapi.yml 已包含此 API 的端點定義
   - 我只需要產生程式碼

2️⃣ 需要更新
   - doc/openapi.yml 存在但需要加入新的端點
   - 我需要協助修改規格

3️⃣ 尚未定義
   - doc/openapi.yml 不存在或沒有此端點
   - 我需要從頭建立規格

問題 3：需要實作的分層

code

請選擇需要實作的分層（可多選）：

☑️ Controller
   - HTTP 請求處理與路由
   - 請求驗證
   - HTTP 狀態碼對應

☑️ Handler
   - 業務邏輯處理
   - 流程協調
   - 錯誤處理與結果封裝

☑️ Repository
   - 資料存取邏輯
   - EF Core 操作
   - 資料庫查詢封裝

提示：通常需要三層都實作以完成完整功能

問題 4：是否產生 Client SDK

code

是否需要產生 Client SDK？

1️⃣ 是，產生 Client SDK
   - 自動產生強型別 API 客戶端
   - 前端可直接使用
   - 完整的 IntelliSense 支援
   - 產生位置：JobBank1111.Job.Contract/AutoGenerated/

2️⃣ 否，暫不產生
   - 僅產生 Server Controller
   - 後續可隨時執行 task codegen-api-client

OpenAPI 規格範本

端點定義範例

yaml

paths:
  /api/v1/members:
    post:
      summary: 建立新會員
      operationId: CreateMember
      tags:
        - Member
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMemberRequest'
      responses:
        '201':
          description: 會員建立成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponse'
        '400':
          description: 請求驗證失敗
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
        '409':
          description: Email 已被使用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
        '500':
          description: 內部伺服器錯誤
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'

components:
  schemas:
    CreateMemberRequest:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: "張三"
        phone:
          type: string
          pattern: '^\d{10}$'
          example: "0912345678"

    MemberResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time

程式碼產生命令

Server Controller 產生

bash

# 執行 Taskfile 命令
task codegen-api-server

# 產生位置
# JobBank1111.Job.WebAPI/Contract/AutoGenerated/

Client SDK 產生

bash

# 執行 Taskfile 命令
task codegen-api-client

# 產生位置
# JobBank1111.Job.Contract/AutoGenerated/

Controller 實作指導

產生的 Controller 骨架需要實作自動產生的介面，整合以下元件：

•Handler 整合：呼叫業務邏輯層
•Result Pattern 處理：轉換 Result 為 HTTP 回應
•HTTP 狀態碼映射：使用 FailureCodeMapper

完整實作範本請參考：assets/controller-template.cs

API First vs Code First 對比

比較項目	API First（推薦）	Code First
文件同步	✅ 自動 100% 同步	❌ 需手動維護
前後端協作	✅ 可並行開發	⚠️ 需等後端完成
契約保證	✅ 編譯時檢查	❌ 執行時才發現
Client SDK	✅ 自動產生	❌ 需手動實作
開發速度	⚠️ 需先設計 API	✅ 快速啟動
維護成本	✅ 低（自動同步）	❌ 高（手動維護）
團隊協作	✅ 優秀	⚠️ 一般
適用場景	中大型專案、團隊協作	小型專案、快速原型

完整開發流程範例（API First）

步驟 1：定義 OpenAPI 規格

編輯 doc/openapi.yml，新增 API 端點定義。

步驟 2：產生 Server Controller

bash

task codegen-api-server

產生檔案：

•JobBank1111.Job.WebAPI/Contract/AutoGenerated/IMemberApi.cs（介面）

步驟 3：實作 Controller

建立 MemberController.cs 實作自動產生的介面：

csharp

[ApiController]
[Route("api/v1/members")]
public class MemberController(MemberHandler handler) : ControllerBase, IMemberApi
{
    public async Task<IActionResult> CreateMember(
        CreateMemberRequest request,
        CancellationToken cancellationToken = default)
    {
        var result = await handler.CreateMemberAsync(request, cancellationToken);

        return result.Match(
            success => StatusCode(201, success),
            failure => StatusCode(
                FailureCodeMapper.ToHttpStatusCode(failure.Code),
                failure)
        );
    }
}

步驟 4：產生 Client SDK（可選）

bash

task codegen-api-client

產生檔案：

•JobBank1111.Job.Contract/AutoGenerated/IMemberApi.cs（Client 介面）
•JobBank1111.Job.Contract/AutoGenerated/MemberApiClient.cs（Client 實作）

參考文件

•API 開發工作流程詳解

範本檔案

•Controller 實作範本
•OpenAPI 端點範本

注意事項

🔒 核心原則

•強制詢問：不得擅自假設開發流程，必須明確詢問
•文件優先：API First 時，規格定義必須在實作之前
•自動產生的程式碼不可手動編輯：位於 AutoGenerated 資料夾

📋 最佳實踐

•API First 優先：除非有特殊理由，建議使用 API First
•規格完整性：確保 OpenAPI 規格包含完整的錯誤回應定義
•版本控制：API 路徑應包含版本號（如 /api/v1/）
•一致性：遵循現有 API 的命名與結構風格

✅ 成功指標

• OpenAPI 規格正確定義（API First）
• Server Controller 成功產生
• Controller 正確實作介面
• Client SDK 成功產生（如需要）
• API 文件與實作同步

錯誤處理

codegen 命令失敗

code

❌ 錯誤：無法產生程式碼

執行命令：task codegen-api-server
錯誤訊息：OpenAPI 規格格式錯誤

建議：
1. 檢查 doc/openapi.yml 格式是否正確
2. 使用線上驗證工具：https://editor.swagger.io/
3. 確認 YAML 縮排正確（使用空格，不使用 Tab）

產生的 Controller 編譯失敗

code

❌ 錯誤：Controller 編譯失敗

錯誤訊息：CS0535: 'MemberController' does not implement interface member 'IMemberApi.CreateMember'

建議：
1. 確認方法簽章與介面定義完全一致
2. 檢查參數名稱、類型、回傳類型
3. 參考範本：assets/controller-template.cs

API Development Skill

描述

職責

能力

1. 開發流程決策引導

2. OpenAPI 規格管理

3. 程式碼自動產生

4. Controller 實作協助

使用方式

在 GitHub Copilot 中使用

直接呼叫 Skill

互動流程

互動問答範例

問題 1：API 開發流程選擇

問題 2：OpenAPI 規格定義狀態（僅 API First）

問題 3：需要實作的分層

問題 4：是否產生 Client SDK

OpenAPI 規格範本

端點定義範例

程式碼產生命令

Server Controller 產生

Client SDK 產生

Controller 實作指導

API First vs Code First 對比

完整開發流程範例（API First）

步驟 1：定義 OpenAPI 規格

步驟 2：產生 Server Controller

步驟 3：實作 Controller

步驟 4：產生 Client SDK（可選）

參考文件

範本檔案

注意事項

🔒 核心原則

📋 最佳實踐

✅ 成功指標

錯誤處理

codegen 命令失敗

產生的 Controller 編譯失敗

相關 Skills

相關 Agents