接口文檔怎麼寫：從代碼生成 API 接口文檔提示詞（參數表、返回示例、錯誤碼 + OpenAPI）
後端寫完接口要交給前端、測試或第三方對接時用：貼上路由和處理函數代碼，生成按統一模板整理的接口文檔（含參數約束、返回示例、錯誤碼、鑑權說明），並可同時輸出 OpenAPI 3 草稿，導入 Apifox、Postman 等工具。
通用大模型 對話模型通用
【角色】你是一名同時做過後端和對外開放平台的技術文檔工程師，知道對接方最常問的是：要不要登入、哪些字段必填、出錯返回什麼、能不能重試。 【背景】 - 服務與框架：[框架，如 Spring Boot/FastAPI] - 文檔讀者：[前端/測試/外部合作方] - 統一的返回結構與錯誤碼約定（沒有就寫無）：[統一返回結構] - 鑑權方式：[如 Bearer Token/Cookie/簽名] - 接口代碼（路由定義、請求模型、處理函數、相關的數據模型）： [粘貼接口代碼] 【任務】對每個接口輸出： 1. 基本資訊：接口名稱、用途一句話、請求方法與路徑、是否需要登入及所需權限。 2. 請求參數表：位置（path/query/header/body）| 字段 | 類型 | 必填 | 預設值 | 取值約束（長度、範圍、枚舉、格式）| 示例 | 說明。嵌套對象用「父字段.子字段」展開。 3. 請求示例：curl 一條 + JSON 請求體。 4. 成功響應：字段表 + JSON 示例；分頁接口寫清分頁參數、最大頁大小和排序規則。 5. 錯誤響應：HTTP 狀態碼 | 業務錯誤碼 | 觸發條件 | 調用方應如何處理。 6. 調用須知：冪等性（重複提交會怎樣）、是否可安全重試、頻率限制、時間字段的時區與格式、金額單位。 7. 最後輸出這些接口的 OpenAPI 3.0 YAML 草稿。 【約束】 - 只寫代碼裏能看出來的資訊；代碼中看不出的（如頻率限制、權限名），寫「待確認」並彙總到最後，不要猜測。 - 示例數據使用明顯虛構的值，不出現真實手機號、電郵、密鑰。 - 發現代碼與常見規範不一致的地方（如 GET 接口修改數據、錯誤時仍返回 200、缺少參數校驗），在文末「接口設計建議」裏單獨列出，不要擅自改寫文檔掩蓋問題。 【輸出格式】 Markdown：每個接口一個二級標題，按上面 1–6 的順序；然後是 OpenAPI YAML 代碼塊；最後是「待確認」和「接口設計建議」兩個清單。
高亮處換成你自己的內容：[前端/測試/外部合作方]、[統一返回結構]、[粘貼接口代碼]
ChatGPT Plus 充值
已被複製 0 次
使用說明
怎麼填變量：只貼路由函數不夠，要連同請求/響應的數據模型（DTO、Pydantic 模型、校驗註解）一起貼，參數約束全靠它們推斷。[文檔讀者] 是外部合作方時，模板會更強調鑑權、簽名、重試和錯誤處理；給內部前端看則可以簡略。
常見坑：
- 代碼裏沒寫的東西（頻率限制、權限點）AI 很容易「合理補全」，一定要看「待確認」清單逐條核對。
- 分頁接口要寫清 page 從 0 還是 1 開始，這是對接中最常見的扯皮點。
- 金額、時間字段務必寫明單位和時區，例如「金額單位為分」「時間為 ISO 8601，帶時區」。
追問技巧：生成後追問「站在前端角度，按這份文檔對接還缺什麼資訊」；接口改動後把 diff 貼回去，說「只更新受影響的字段，並在文檔開頭加一條變更記錄」。
示例輸出
示例，僅供參考（節選）
GET /api/orders/{id} 查詢訂單詳情（需要登入，只能查看自己的訂單）
| 狀態碼 | 業務碼 | 觸發條件 | 調用方處理 |
|---|---|---|---|
| 401 | AUTH_REQUIRED | 未登入或 token 過期 | 跳轉登入 |
| 404 | ORDER_NOT_FOUND | 訂單不存在或不屬於當前用戶 | 提示「訂單不存在」 |
yaml
openapi: 3.0.3
info:
title: 訂單服務
version: 1.0.0
paths:
/api/orders/{id}:
get:
summary: 查詢訂單詳情
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: 成功
'404':
description: 訂單不存在或不屬於當前用戶
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer同款作品
用這條提示詞做出來的作品；原作者會因此獲得積分
還沒有同款，來做第一個。
0 條評論
還沒有評論，來搶沙發～