要快速且易於理解的API集成,需要結構化的文檔。我們使用OpenAPI 3規範。0+（以前稱為Swagger），它允許以單一標準化格式描述所有API方法，參數和模型，並具有代碼生成，測試和導出SDK的功能。
這降低了開發人員的登錄閾值，加快了集成，並消除了與不完整或過時的接口描述相關的錯誤。
OpenAPI/Swagger給出的內容
| 一個機會 | 優點 |
|---|---|
| 交互式文檔 | Swagger UI能夠在瀏覽器中直接測試API |
| SDK生成 | 自動創建不同語言的客戶端庫 |
| 按標準排列的結構 | 描述所有殘局、參數、答案、錯誤和授權 |
| 機器可讀性 | API可以驗證、蒸發、導出和連接到CI/CD |
| 相關性 | 文檔在API更改時自動更新 |
如何實現
OpenAPI 3格式的API說明。0（.yaml或。json)
能夠生成Postman集合和SDK （cURL, JS, PHP, Python, Java和Go）
授權支持： API key, JWT, OAuth2
可視化顯示可用查詢和可能的響應
直接從文檔中測試API （Swagger UI/Redoc）
對開發人員的好處
快速連接而無需手動分析結構
支持IDE和代碼生成器（Swagger Codegen, OpenAPI Generator）
文檔始終與當前的API匹配
方便傳輸給合作夥伴和集成商
改進DX（開發者體驗）和實施速度
在哪裏，特別重要
具有開放或公共API的項目
從事API優先方法的團隊
具有外部集成和合作夥伴連接的平臺
使用後端API的移動和前端應用程序