api-development

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

⚠️ 前置條件

本 SKILL 須搭配閱讀：

• 開發規則
• 決策框架 - API 開發流程

API Development Skill

描述

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

職責

• 引導選擇 API First 或 Code First 開發流程
• 協助更新/建立 OpenAPI 規格（doc/openapi.yml，相對於套用範本後的目標專案根目錄）；OpenAPI 規格會自動透過 FileResolver 取得，開發者可在本地 dotnet-project-template/doc/openapi.yml 編輯
  • 取得規格: node .claude/skills/shared/FileResolver.js get-content dotnet-project-template/doc/openapi.yml
• 產生 Server Controller 骨架
• 產生 Client SDK
• 提供 Controller 實作指導

能力

1. 開發流程決策引導

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

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

2. OpenAPI 規格管理

• 使用 FileResolver 自動解析 doc/openapi.yml（本地優先，找不到時自動從 GitHub 取得，無需手動下載範本專案）
• 引導新增/修改 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 中使用

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

直接呼叫 Skill

使用 api-development 開發 API

互動流程

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 開發流程選擇

請選擇 API 開發流程：

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

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

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

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

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

請確認 OpenAPI 規格狀態：

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

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

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

問題 2.5：確認 API 開發方式

請確認此專案的 API 開發方式：

1️⃣ API First（推薦用於團隊協作、Client SDK 需求）
   - 預先定義 OpenAPI 規格（openapi.yaml）
   - 自動產生 Controller 骨架
   - 命名約定：XxxControllerImpl
   - 適用：公開 API、大型團隊、Client SDK 分發

2️⃣ Code First（推薦用於快速原型、內部小型專案）
   - 直接編寫 Controller 類別，無預先規格
   - 使用 Route 和 HttpMethod 特性定義端點
   - 命名約定：XxxController（無 Impl 後綴）
   - 適用：快速原型、內部 API、小型團隊

⚠️ 重要：同一專案內只能選擇一種方式，不得混用

問題 3：需要實作的分層

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

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

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

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

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

問題 4：是否產生 Client SDK

是否需要產生 Client SDK？

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

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

OpenAPI 規格範本

端點定義範例

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: "[e-mail]"
        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 產生

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

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

Client SDK 產生

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

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

Controller 實作指導

API First: 實作自動產生的介面

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

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

命名約定：使用 XxxControllerImpl 命名（Impl 後綴表示 API First 實作）

完整實作範本請參考生產代碼（透過 FileResolver）：

node .claude/skills/shared/FileResolver.js get-content \
  JobBank1111.Job.WebAPI/Member/MemberV1ControllerImpl.cs

Code First: 直接實作無預先介面

無需實作自動產生的介面，直接建立 Controller 類別實作業務邏輯：

1. 直接定義 API 端點：使用 Route 和 HttpMethod 特性
2. Handler 整合：同樣呼叫業務邏輯層
3. Result Pattern 處理：同樣轉換 Result 為 HTTP 回應
4. HTTP 狀態碼映射：同樣使用 FailureCodeMapper

命名約定：使用 XxxController 命名（無 Impl 後綴表示 Code First 實作）

重要提醒：Code First 開發完成後，需手動維護 OpenAPI 規格文件以保持文件同步。

API First vs Code First 對比

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

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

步驟 1：定義 OpenAPI 規格

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

OpenAPI 規格會自動透過 FileResolver 取得（本地優先，找不到時從 GitHub 下載並快取）。開發者可在本地 dotnet-project-template/doc/openapi.yml 直接編輯。

步驟 2：產生 Server Controller

task codegen-api-server

產生檔案：

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

步驟 3：實作 Controller

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

[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)
        );
    }
}

Code First 完整開發流程

Code First 開發方式適用於快速原型、內部小型專案或需要高度定制的場景。與 API First 不同，Code First 無需預先定義 OpenAPI 規格，而是直接撰寫 Controller 類別。

開發流程步驟

Code First 步驟 1：直接建立 Controller 類別

無需預先產生 OpenAPI 規格，直接建立 MemberController.cs（無 Impl 後綴）：

[ApiController]
[Route("api/v2/members")]
public class MemberController(MemberHandler handler) : ControllerBase
{
    [HttpPost]
    [ProducesResponseType(typeof(MemberDto), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(FailureResponse), StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> CreateMember(
        [FromBody] 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)
        );
    }

    [HttpGet("{id}")]
    [ProducesResponseType(typeof(MemberDto), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(FailureResponse), StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetMember(
        [FromRoute] int id,
        CancellationToken cancellationToken = default)
    {
        var result = await handler.GetMemberAsync(id, cancellationToken);

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

    [HttpPut("{id}")]
    [ProducesResponseType(StatusCodes.Status204NoContent)]
    [ProducesResponseType(typeof(FailureResponse), StatusCodes.Status404NotFound)]
    public async Task<IActionResult> UpdateMember(
        [FromRoute] int id,
        [FromBody] UpdateMemberRequest request,
        CancellationToken cancellationToken = default)
    {
        var result = await handler.UpdateMemberAsync(id, request, cancellationToken);

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

    [HttpDelete("{id}")]
    [ProducesResponseType(StatusCodes.Status204NoContent)]
    [ProducesResponseType(typeof(FailureResponse), StatusCodes.Status404NotFound)]
    public async Task<IActionResult> DeleteMember(
        [FromRoute] int id,
        CancellationToken cancellationToken = default)
    {
        var result = await handler.DeleteMemberAsync(id, cancellationToken);

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

關鍵特徵：

• 無需實作任何介面
• 使用 Route 和 HttpMethod 特性（HttpPost、HttpGet 等）直接定義端點
• 使用 ProducesResponseType 特性文件化 HTTP 回應
• 與 API First 相同的 Handler 整合和 Result Pattern 處理

Code First 步驟 2：實作 Handler 和業務邏輯

與 API First 完全相同，實作 MemberHandler 和相關的 DTO、實體。

Code First 步驟 3：維護 OpenAPI 規格文件

使用工具產生初始 OpenAPI 規格，或手動編寫規格文件以保持一致性：

• 自動產生：Swashbuckle 從 Controller 特性自動產生 OpenAPI 規格
• 手動維護：在 docs/openapi.yaml 手動編寫規格，並定期與代碼同步

Code First 步驟 4：客戶端整合

Code First 開發完成後，可選擇自動產生 Client SDK 或手動實作 HTTP 客戶端。

開發時間線對比

階段	API First	Code First
規格設計	1-2 小時	0 小時（無預先規格）
Code 產生	10 分鐘	0 小時（無自動產生）
實作階段	2-3 小時	2-3 小時
文件同步	0 小時	1-2 小時（手動維護）

適用場景

Code First 推薦：

• 快速原型開發（時間優先）
• 內部 API（無需外部 SDK 分發）
• 小型團隊（無需複雜的 API 溝通流程）
• 實驗性功能（規格可能頻繁變動）

API First 推薦：

• 公開 API（需要穩定的規格契約）
• 大型團隊協作（預先溝通 API 結構）
• Client SDK 分發（自動產生多種語言）
• 文件優先開發（詳細的 API 文件）

Code First 實作參考

生產代碼範例（透過 FileResolver）：

node .claude/skills/shared/FileResolver.js get-content \
  JobBank1111.Job.WebAPI/Member/MemberController.cs

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

task codegen-api-client

產生檔案：

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

參考檔案

💡 獨立用戶提示：所有檔案參考自動使用 FileResolver 工具。 即使您沒有下載完整專案，SKILL 也會自動從 GitHub 取得所需的範本與文檔。 無需手動下載 dotnet-project-template。

參考文件

• API 開發工作流程詳解

參考代碼

💡 所有範本已改為使用 FileResolver 動態取得真實項目代碼，確保始終同步更新。

取得真實實作範例：

# Controller 實作
node .claude/skills/shared/FileResolver.js get-content \
  JobBank1111.Job.WebAPI/Member/MemberV1ControllerImpl.cs

# Handler 實作  
node .claude/skills/shared/FileResolver.js get-content \
  JobBank1111.Job.WebAPI/Member/MemberHandler.cs

注意事項

🔒 核心原則

1. 強制詢問：不得擅自假設開發流程，必須明確詢問使用者選擇 API First 或 Code First
2. 文件優先（API First）：API First 開發時，OpenAPI 規格定義必須在實作之前
3. 文件同步（Code First）：Code First 開發時，完成實作後必須手動維護 OpenAPI 規格文件以保持一致性
4. 禁止混用：同一專案內只能選擇一種開發方式（API First 或 Code First），不得混用
5. 命名約定：
   • API First：使用 XxxControllerImpl 命名（Impl 後綴表示由規格自動產生的實作）
   • Code First：使用 XxxController 命名（無 Impl 後綴表示直接實作）
   • 自動產生的程式碼不可手動編輯，位於 AutoGenerated 資料夾

📋 最佳實踐

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

✅ 成功指標

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

錯誤處理

codegen 命令失敗

❌ 錯誤：無法產生程式碼

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

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

產生的 Controller 編譯失敗

❌ 錯誤：Controller 編譯失敗

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

建議：
1. 確認方法簽章與介面定義完全一致
2. 檢查參數名稱、類型、回傳類型
3. 參考專案內的實際 Controller 實作

相關 Skills

API 開發方式相關：

• /api-development - API First vs Code First 決策與流程選擇

與開發方式無關的實作 Skills（API First 和 Code First 均適用）：

• /handler - Handler 業務邏輯實作（兩種方式通用）
• /error-handling - Result Pattern 錯誤處理（兩種方式通用）
• /bdd-testing - API 端點 BDD 測試（兩種方式通用）
• /repository-design - 資料存取層設計（兩種方式通用）
• /ef-core - EF Core 最佳化（兩種方式通用）
• /caching-strategy - 快取設計（兩種方式通用）

相關文檔：

• development-rules.md - 開發規則與 Controller 命名約定
• decision-framework.md - API 決策框架

相關 Agents

• feature-development-agent - 完整功能開發流程（整合此 skill 的決策節點）
• architecture-review-agent - 架構檢視（驗證 API 層設計是否遵循原則）