本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。
專案摘要
- 開放原始碼組織：
- OWASP Foundation
- 技術撰稿人：
- sshniro
- 專案名稱：
- 強化 ZAP API 說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
ZAP 具有非常強大的 API，可讓我們透過桌面介面完成幾乎所有工作。不過，如要有效使用 API，就必須充分瞭解 UI。這是因為大部分的 API 都與 ZA Proxy 的使用者介面直接相關。如果使用 API 和用途/ 用途文件，在試用 API 時可以協助克服這個瓶頸。
目前，API 文件是由系統自動產生，所提供的參數相關資訊很少，而社群也能更少參與 API 說明文件。此外，在 ZAP 中使用的網頁式使用者介面 (電腦版) 也會使用自動產生的 API 清單進行叫用。這個網頁式 API 叫用 UI 也提供了非常有限的資訊，說明 API 的使用方式和叫用 API 後的注意事項 ( 例如 API 結果)。因此，在這個提案中，我會建議記錄 API 的新方法。
其做法是使用 Open API 3 規格重新建立 API 文件。開放式 API 為開發人員、測試人員和開發運作人員提供通用架構，可用於建構、維護及測試 API。針對 ZAP 完成的 Open API 規格可用來自動產生 Swagger 檔案。Swagger 檔案可以整合至 ZAP 的網頁應用程式 (桌面應用程式) UI，為使用者提供豐富的 API 測試用戶端。
除了 API 說明文件之外，我也打算使用 swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) 轉換工具產生 Markdown 格式的 API 文件。這個方法 (swagger-Converter) 結合了以 Swagger 產生的自動產生的 API 說明文件，簡化了最新符合 REST 樣式的 API 說明文件。結果會與 GitHub 的 API 說明文件類似。(https://developer.github.com/v3/)。這份手寫文件包含概略文件，說明如何使用 API 執行特定工作。例如，Spider API 掃描是一項長時間執行的工作，而使用者應持續輪詢 API 以瞭解該 API 的狀態。因此，這些高階文件會討論要使用哪些 API 執行動作，並指向自動產生的 Swagger 文件，以便進一步閱讀。
我們總共在 ZA Proxy 中實作了 380 多個 API。我一開始提議將所有 API 的相關說明包括 API 的說明、參數、成功與失敗回應相關資訊。已完成聯絡窗口範例，您可以在連結的提案中查看其他詳細資料。
三個月的期間將分為三個階段。第一階段將為 Active Scan、Core API (150+) 建立 Open API 規格。除了建立 Swagger 檔案之外，我們也會建立相關用途說明文件/ 高階文件，說明如何使用 API 執行特定工作。這可以自動產生版本和自動產生，藉此移除人工作業。您也可以將 Markdown 檔案代管為網頁，或以 PDF 格式匯出。
第二階段將介紹 Spider、Autoupdate、Context、Status、Search API，以及透過 Markdown 檔案建立相關用途文章。
最後階段將涵蓋其他未記錄的 API 及其相關用途。上個月，我計劃納入需要叫用多個 API 元件來執行任務的應用實例。