快速入門：30 分鐘內從規格到運行的 API

這就是事情變得真實的地方。在接下來的 30 分鐘內，您將從 Apidog 中的 API 設計轉變為在您電腦上執行的完全可運作的 API。不需要數週的學習。不需要數百行的手動編碼。只有結果。

這是我們要做的：

從 Apidog 匯出您的 API 設計（2 分鐘）

使用 Cursor 生成完整的專案（10 分鐘）

在本地執行它（5 分鐘）

我們開始吧。

匯出您的 API 規格（2 分鐘）

您在 Apidog 中的 API 設計包含 AI 生成程式碼所需的一切。您只需要匯出它。

在 Apidog 中打開您的 User API 專案

確保您已完成「設計 API」章節並擁有包含所有六個端點的 User 模組：

POST /users (註冊)

POST /user/login

GET /users/{id}

PUT /users/{id}

DELETE /users/{id}

POST /user/logout

匯出 OpenAPI 規格

點擊左上角的專案名稱
2.前往 Settings → Import/Export

點擊 Export → OpenAPI

選擇 OpenAPI 3.0 (不是 3.1)

格式：JSON (AI 更容易讀取)

點擊 Export

您將獲得一個名為 user-api.json 之類的檔案。將其儲存在您可以輕鬆找到的地方（如桌面）。

您剛剛匯出了什麼

在任何文字編輯器中打開該檔案。您將看到描述整個 API 的 JSON - 您所有的端點、請求和回應 schemas、身分驗證需求以及資料驗證規則。這個檔案是 AI 用來構建您 API 的藍圖。

使用 Cursor 生成您的專案（10 分鐘）

現在是神奇的部分。您將把這個規格提供給 Cursor，並看著它生成一個完整的、可運作的專案。

建立專案資料夾

在有組織的地方建立一個新資料夾：

或者就建立在您保存專案的任何地方。位置並不重要。

在 Cursor 中打開資料夾

啟動 Cursor

File → Open Folder

選擇您剛剛建立的資料夾

加入您的 API 規格

將匯出的 user-api.json 檔案拖入 Cursor 的檔案檔案總管。它應該出現在側邊欄中。

打開 Cursor Composer

按 Cmd+I (Mac) 或 Ctrl+I (Windows/Linux)。這將打開 Composer 模式，它可以生成整個專案。

使用此提示詞

複製這整個提示詞並將其貼上到 Composer 中：

I have an OpenAPI 3.0 specification in user-api.json. Generate a complete, production-ready Python FastAPI project that implements this spec exactly.

TECH STACK:
- FastAPI (web framework)
- SQLAlchemy (ORM)
- SQLite for development (easy PostgreSQL migration later)
- JWT authentication (python-jose)
- Password hashing (passlib with bcrypt)
- Pydantic v2 (validation)
- Uvicorn (ASGI server)

REQUIREMENTS:
1. Implement ALL endpoints from the OpenAPI spec
2. Request/response formats must match the spec exactly
3. All HTTP status codes as specified
4. JWT token generation and validation
5. Password hashing (never store plain text)
6. Proper error handling with meaningful messages
7. Input validation matching the schemas
8. CORS enabled for local development
9. Clear code comments explaining key parts

PROJECT STRUCTURE:

user-api/
├── main.py # App entry point, routes registration
├── database.py # Database connection and session
├── auth.py # JWT token functions
├── dependencies.py # Reusable dependencies (get_db, get_current_user)
├── models/
│ └── user.py # SQLAlchemy database model
├── schemas/
│ └── user.py # Pydantic request/response models
├── routers/
│ └── users.py # All user endpoints
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # Setup and run instructions


IMPORTANT DETAILS:
- Email must be unique (database constraint)
- Password field is write-only (never return it)
- Protected endpoints require valid JWT in Authorization header
- User can only modify/delete their own account
- Tokens expire after 24 hours
- createdAt and updatedAt timestamps auto-managed
- All string inputs trimmed
- Proper HTTP status codes (200, 201, 204, 400, 401, 403, 404, 422)

Generate all files with complete, working code. Make sure it can run immediately after pip install.

按 Enter 並看著 Cursor 生成您的專案。這大約需要 1-2 分鐘。您將看到它逐一建立檔案：main.py, database.py, auth.py 以及其他所有檔案。

審查生成的內容

完成後，您應該有 8-10 個檔案。在 Cursor 的側邊欄中點擊瀏覽它們。您不需要理解所有內容，但請注意這是大量您不需要手動編寫的可運作程式碼。程式碼有註釋、適當的結構，並符合您的 API 規格。

如果看起來有問題或缺少檔案，您可以要求 Cursor 修復："You forgot to create .env.example, please add it"

在本地執行您的 API（5 分鐘）

讓我們讓這個東西跑起來。

打開 Cursor 中的終端機

按 Ctrl+` (反引號鍵，通常在 Tab 上方)。這將在 Cursor 底部打開一個終端機。

建立並啟用虛擬環境

這可以將您的專案依賴項隔離：

您應該在終端機提示符的開頭看到 (venv)。

安裝依賴項

這將安裝 FastAPI, SQLAlchemy 以及您的 API 所需的一切。大約需要 30-60 秒。

執行 API

或

您應該看到類似以下的輸出：

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

您的 API 現在正在執行！

快速驗證

打開瀏覽器並前往：

http://localhost:8000/docs

您應該看到 FastAPI 的自動文件 (Swagger UI) 顯示所有端點。如果您看到這個頁面列出了您的六個端點，那麼一切運作完美。

您剛剛做了什麼

在大約 15 分鐘內，您：

✅ 從 Apidog 匯出了您的 API 設計作為 OpenAPI 規格
✅ 使用 AI 生成了一個包含資料庫、身分驗證和驗證的完整 FastAPI 專案
✅ 在本地執行它且沒有錯誤
✅看到了您 API 的互動式文件

您剛剛生成的 API 包含：

六個完全實作的端點

JWT 身分驗證

使用 bcrypt 的密碼雜湊

使用 SQLAlchemy ORM 的 SQLite 資料庫

使用 Pydantic 的輸入驗證

適當的錯誤處理

開發環境的 CORS 支援

所有這些都完全符合您的 OpenAPI 規格。而且您沒有手動編寫任何一行程式碼。

快速疑難排解

"Module not found" 錯誤

確保您啟用了虛擬環境

再次執行 pip install -r requirements.txt

"Port 8000 already in use"

其他東西正在使用埠 8000

在不同的埠上執行：uvicorn main:app --reload --port 8001

Cursor 沒有生成所有檔案

詢問它："Please review the project structure and create any missing files"

下一步是什麼

您有一個在電腦上執行的可運作 API。但在我們在 Apidog 中正確測試它之前，讓我們了解這段程式碼實際上做了什麼。

在下一章中，我們將瀏覽生成的檔案並解釋一切是如何組合在一起的。您將了解路由如何運作，身分驗證如何實作，資料庫如何結構化，以及請求如何在您的 API 中流動。

繼續閱讀 → 了解生成的程式碼

快速入門：30 分鐘內從規格到運行的 API

匯出您的 API 規格（2 分鐘）#

使用 Cursor 生成您的專案（10 分鐘）#

在本地執行您的 API（5 分鐘）#

您剛剛做了什麼#