openapi-to-application-code

從 OpenAPI 規格產生應用程式

你的目標是根據 OpenAPI 規格，使用當前框架的慣例與最佳實務，產生一個完整、可運作的應用程式。

輸入需求

1. OpenAPI 規格：提供以下任一方式：

   • OpenAPI 規格的 URL（例如 https://api.example.com/openapi.json）
   • OpenAPI 規格的本地檔案路徑
   • 直接貼上完整的 OpenAPI 規格內容

2. 專案詳細資訊（若規格中未包含）：

   • 專案名稱與描述
   • 目標框架與版本
   • 套件/命名空間命名慣例
   • 驗證方式（若 OpenAPI 未指定）

產生流程

步驟 1：分析 OpenAPI 規格

• 驗證 OpenAPI 規格的完整性與正確性
• 識別所有端點、HTTP 方法、請求/回應結構
• 擷取驗證需求與安全機制
• 注意資料模型之間的關係與限制
• 標記任何不明確或不完整的定義

步驟 2：設計應用程式架構

• 規劃符合框架的目錄結構
• 依資源或領域分組控制器/處理器
• 設計服務層組織以處理商業邏輯
• 規劃資料模型與實體關係
• 設計設定與初始化策略

步驟 3：產生應用程式程式碼

• 建立專案結構，包含建置/套件設定檔
• 從 OpenAPI 結構產生模型/DTO
• 產生控制器/處理器與路由對應
• 產生服務層與商業邏輯
• 產生儲存庫/資料存取層（若適用）
• 加入錯誤處理、驗證與日誌記錄
• 產生設定與啟動程式碼

步驟 4：加入輔助檔案

• 產生適當的單元測試（服務與控制器）
• 建立 README，包含設定與執行說明
• 加入 .gitignore 與環境設定範本
• 產生 API 文件檔案
• 建立範例請求/整合測試

輸出結構

產生的應用程式將包含：

project-name/
├── README.md                      # 設定與使用說明
├── [build-config]                 # 框架專屬建置檔（pom.xml、build.gradle、package.json 等）
├── src/
│   ├── main/
│   │   ├── [language]/
│   │   │   ├── controllers/       # HTTP 端點處理器
│   │   │   ├── services/          # 商業邏輯
│   │   │   ├── models/            # 資料模型與 DTO
│   │   │   ├── repositories/      # 資料存取（若適用）
│   │   │   └── config/            # 應用程式設定
│   │   └── resources/             # 設定檔
│   └── test/
│       ├── [language]/
│       │   ├── controllers/       # 控制器測試
│       │   └── services/          # 服務測試
│       └── resources/             # 測試設定
├── .gitignore
├── .env.example                   # 環境變數範本
└── docker-compose.yml             # 可選：Docker 設定（若適用）

採用的最佳實務

• 框架慣例：遵循框架特定的命名、結構與模式
• 關注點分離：明確的控制器、服務與儲存庫層
• 錯誤處理：全面的錯誤處理，提供有意義的回應
• 驗證：輸入驗證與結構驗證貫穿全流程
• 日誌記錄：結構化日誌，便於除錯與監控
• 測試：服務與控制器的單元測試
• 文件：行內程式碼文件與設定說明
• 安全性：根據 OpenAPI 規格實作驗證/授權
• 可擴展性：設計模式支援成長與維護

後續步驟

產生後：

1. 檢視產生的程式碼結構，並依需求進行客製化
2. 根據框架需求安裝相依套件
3. 設定環境變數與資料庫連線
4. 執行測試以驗證產生的程式碼
5. 啟動開發伺服器
6. 使用提供的範例測試端點

需要時可詢問的問題

• 應用程式是否應包含資料庫/ORM 設定，或僅使用記憶體/模擬資料？
• 是否需要 Docker 設定以進行容器化？
• 驗證方式應為 JWT、OAuth2、API 金鑰或基本驗證？
• 需要整合測試還是僅單元測試？
• 是否有偏好的資料庫技術？
• API 是否應包含分頁、篩選與排序範例？