OpenAPI Specification
OpenAPI 規格
OpenAPI 規格是一種不綁定程式語言的 HTTP API 描述方式。它包含操作、輸入、資料格式、安全方案、回應和可重用的綱要。
另一個例子
合作夥伴 API 描述 `POST /claims`、必填的冪等標頭、OAuth 範圍、JSON Schema 規則、201 與問題回應，以及使用假資料的範例。CI 會擋下沒有寫進文件的破壞性回應。自動產生的用戶端仍要審查，不能直接假設正確。
主要部分
- 01API 中繼資料與 Server
- 02路徑與操作
- 03Schema、安全與回應
什麼時候用
把它當成可供審查的契約，用於文件、驗證、模擬伺服器、用戶端產生和相容性檢查。
什麼時候不要用
自動產生的文件不能取代真實範例和授權測試。也不能取代執行期間驗證或清楚的正式環境行為。
程式裡的名稱
openapi document: paths, operations, components/schemas, securitySchemes, responses 上線前要檢查
檢查介面約定、任何情況都不能破壞的規則、授權與輸入限制。測試重試、重複執行只生效一次、逾時與部分失敗。驗證資料完整性、相容性、監控、復原與回復上一版。
預期成果：為這套系統設計或檢查 OpenAPI 規格 (OpenAPI Specification)，並讓資料保持正確、安全且容易維護。 使用者情境：合作夥伴 API 描述 `POST /claims`、必填的冪等標頭、OAuth 範圍、JSON Schema 規則、201 與問題回應，以及使用假資料的範例。CI 會擋下沒有寫進文件的破壞性回應。自動產生的用戶端仍要審查，不能直接假設正確。 技術概念或控制措施：OpenAPI 規格 (OpenAPI Specification)。 適用理由：把它當成可供審查的契約，用於文件、驗證、模擬伺服器、用戶端產生和相容性檢查。 不應使用的情況：自動產生的文件不能取代真實範例和授權測試。也不能取代執行期間驗證或清楚的正式環境行為。 工程要求：定義輸入、輸出、介面約定，以及任何情況都不能破壞的規則。說明授權與輸入檢查範圍。定義失敗、逾時、重試和重複執行只生效一次的規則。也要定義資料搬移與相容限制。 營運要求：加入監控訊號與隱藏敏感資料的記錄。設定容量上限並寫好操作手冊。測試復原與回復上一版的流程。 驗收條件：介面約定與失敗路徑測試通過。重試或部分失敗時，資料與授權規則仍正確。效能上限、監控、復原與回復上一版的方法都已驗證。 證據與限制（證據邊界）：正式文件仍可能是草案、候選版或最終版。請查看文件狀態，也要確認瀏覽器或平台是否支援。 待確認：程式執行環境、資料位置、流量形態、資料一致需求和安全邊界。也要確認相容期間、服務目標（SLO）與回復上一版的限制。
檢查這份需求
請 AI 程式助手檢查目前如何使用 OpenAPI 規格 (OpenAPI Specification)。 定義：OpenAPI 規格是一種不綁定程式語言的 HTTP API 描述方式。它包含操作、輸入、資料格式、安全方案、回應和可重用的綱要。 正式環境檢查：檢查介面約定、任何情況都不能破壞的規則、授權與輸入限制。測試重試、重複執行只生效一次、逾時與部分失敗。驗證資料完整性、相容性、監控、復原與回復上一版。 修改程式前，先列出看到的證據、缺口、嚴重程度，以及最小且安全的修正。