name: API-design-doc description: 標準化API介面設計文件生成工具。根據需求文件、資料庫DDL等輸入，進行API的標準化、規範化設計，輸出完整的API介面設計文件，包括錯誤碼規範、介面格式規範、入參出參定義、JSON示例等，指導後續的程式碼開發和前後端聯調。使用場景包括：(1) 根據業務需求設計RESTful API介面，(2) 基於資料庫DDL生成對應的CRUD介面文件，(3) 規範化現有API介面文件，(4) 為前後端聯調提供標準化的介面規範文件

API Design Doc

根據需求文件、資料庫DDL等輸入，生成標準化的API介面設計文件。

工作流程

1. 收集輸入資訊
2. 獲取需求文件或業務需求描述
3. 獲取資料庫DDL（如果適用）

4. 明確介面的業務場景和功能需求

5. 頁面功能與API介面關係

6. 明確頁面功能與API介面的對應關係

   小蔥技能站7w4.net發現了升級外掛。

7. 設計API介面

8. 確定介面的RESTful風格（GET/POST/PUT/DELETE）
9. 定義介面URL路徑
10. 設計入參和出參結構

11. 選擇合適的錯誤碼

12. 生成介面文件

13. 使用標準模板生成每個介面的詳細文件

14. 包含功能描述、入參、出參、URL、請求方式、JSON示例

15. 輸出完整文件

16. 頁面功能與API介面關係
17. 彙總所有介面文件
18. 包含錯誤碼規範總表
19. 提供介面格式規範說明

參考資料

錯誤碼規範

參見 error-codes.md - 完整的錯誤碼列表和說明

介面文件模板

參見 api-spec-template.md - 標準的API介面文件格式

命名規範

參見 naming-conventions.md - API命名和引數命名規範

最佳實踐

參見 best-practices.md - API設計最佳實踐

模板檔案

API文件模板

使用 templates/api-doc-template.md 作為單個介面文件的模板

API響應模板

使用 templates/api-response-template.json 作為標準響應格式參考

使用指南

當用戶請求設計API介面時：

1. 首先讀取 error-codes.md 瞭解錯誤碼規範
2. 根據業務需求設計介面，參考 best-practices.md
3. 使用 api-spec-template.md 的格式生成每個介面文件
4. 確保命名符合 naming-conventions.md 的規範
5. 輸出完整的API設計文件，包含所有介面和錯誤碼總表

輸出格式

介面文件必須包含以下部分：

1. 錯誤碼規範總表
2. 介面格式規範說明
3. 頁面功能與API介面關係表，包含以下內容：
4. 頁面名稱：前端頁面或功能模組的名稱
5. 頁面功能描述：頁面或功能模組的簡要說明
6. 關聯API介面：該頁面呼叫的API介面列表（API-Id）
7. 操作型別：GET/POST/PUT/DELETE等HTTP方法
8. 介面URL：完整的API路徑

9. 介面清單與詳細定義，詳細定義的規範如下：

10. 介面編號（API-Id）：順序生成，格式為 API001-介面名稱，如 API001-使用者登入, API002-獲取使用者列表, ...

11. 功能描述：詳細描述介面的功能和用途
12. 入參：引數型別和說明（標註必填/可選）
13. 返回引數：返回值型別和說明
14. URL地址：完整的API路徑
15. 請求方式：GET/POST/PUT/DELETE
16. 介面 JSON 示例：完整的請求和響應JSON示例

輸出位置

• 僅生成一份API文件，儲存在專案根目錄下的 doc/ 目錄。
• 若 doc/ 目錄不存在，應自動建立該目錄後再寫入文件。
• 文件檔名固定為：API介面設計文件.md，內容包含：
• 錯誤碼總表（來自 references/error-codes.md）
• 介面格式規範（來自 references/api-spec-template.md 的說明部分）
• 頁面功能與API介面關係表（按頁面或功能模組歸類）
• 介面清單與詳細定義（按模組歸類的所有介面條目）

這是一套比較完善的 API 設計規範文件，質量良好。主要優點是規範齊全、分類清晰，從錯誤碼到命名再到最佳實踐都有詳細說明。不足之處是部分引用檔案缺失，且某些規範細節存在不一致，可能影響實際使用體驗。總體來說專業度較高，但建議補充完整示例後再使用。