本頁針對 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 的網頁應用程式 (電腦版應用程式) 使用者介面，為使用者提供豐富的 API 測試用戶端。
除了 API 說明文件之外，我打算使用 swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) 轉換工具產生 Markdown 格式的 API 文件。透過這項方法 (swagger 轉換工具) 結合手動編寫的文件 (使用 Swagger 產生的自動產生 API 文件)，簡化了符合 REST 樣式的最新 API 說明文件。結果會與 GitHub 的 API 說明文件類似。(https://developer.github.com/v3/)。這份手寫文件包含高階文件，其中說明要如何使用 API 執行特定工作。舉例來說，Spider API 掃描是一項長時間執行的工作，使用者應該持續輪詢 API 來瞭解 API 的狀態。因此，這些高階文件會討論要使用哪些 API 執行動作，並指向自動產生的便條文件，以供進一步閱讀。
已在 ZA Proxy 中實作超過 380 個 API。我一開始提議將所有 API 一同記錄下來，包括 API 的參數、成功和失敗回應相關資訊。範例 POC 已完成，其他詳細資料請見連結的提案。
三個月分為三個階段。第一階段會建立 Active Scan 和 Core API (150 以上版本) 的 Open API 規格。在建立 swagger 檔案的同時，我們也會建立有關如何使用 API 執行特定任務的相關用途說明文件/ 高階文件。可以建立版本資訊並自動產生，協助移除人工作業，並將 Markdown 檔案以網頁的形式代管或匯出為 PDF。
第二階段將討論如何記錄 Spider、自動更新、背景資訊、狀態、Search API，並透過 Markdown 檔案建立相關的應用實例文章。
最後一個階段將涵蓋其餘 API 及其相關用途。上個月，我打算也會涵蓋執行任務時需要叫用多個 API 元件的用途。