OWASP Foundation 專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：

OWASP Foundation

技術撰稿人：

sshniro

專案名稱：

強化 ZAP API 說明文件

專案長度：

標準長度 (3 個月)

Project description

ZAP 提供非常強大的 API，可讓我們透過電腦版介面執行幾乎所有可能的操作。不過，如果想有效使用 API，就必須充分瞭解 UI。這是因為大多數 API 都與 ZA Proxy 的使用者介面直接相關。並提供詳盡記錄的 API 和使用情形/ 用途文件，有助於在試用 API 時克服這個瓶頸。

目前，API 文件是由系統自動產生，其中提供的參數相關資訊並不多，社群使用者則比較無法參與 API 說明文件。此外，ZAP 內所使用的網頁式 UI (桌面版本) 也會使用自動產生的 API 清單來進行叫用。這個網頁式 API 叫用 UI 也提供了有限的 API 使用方式資訊，以及叫用 API 時的預期內容 ( 例如 API 結果)。因此，在這個提案中，我建議採用新的 API 文件編寫方式。

這個想法是使用 Open API 3 規格重新建立 API 文件。Open API 提供通用架構，供開發人員、測試人員和開發維運人員建構、維護及測試 API。針對 ZAP 完成的 Open API 規格，可以自動產生 Swagger 檔案。Swagger 檔案可整合至 ZAP 的網路應用程式 (電腦版應用程式) UI，為使用者提供豐富的 API 測試用戶端。

除了 API 說明文件以外，我打算使用 swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) 轉換工具產生 Markdown 格式的 API 文件。這種方法 (Swagger 轉換工具) 結合手寫文件和 Swagger 自動產生的 API 文件，簡化了產生最新 RESTful API 文件的程序。結果會類似於 GitHub 的 API 說明文件。(https://developer.github.com/v3/)。這份手寫文件將包含概略文件，說明如何使用 API 執行特定工作。舉例來說，Spider API 掃描是一項長時間執行的工作，使用者應持續輪詢 API 來瞭解 API 狀態。因此，這些高階文件會討論要使用哪些 API 執行動作，並指向自動產生的 Swagger 文件，供您進一步閱讀。

ZA Proxy 已實作總計 380 多個 API。我最初建議將所有 API 納入說明文件，並提供 API 說明、參數相關資訊、API 成功和失敗回應。我們已完成範例 POC，您可以在連結的提案中查看更多詳細資訊。

這段三個月的時間將分為三個階段。第一階段會為 Active Scan 和核心 API (超過 150 個) 建立 Open API 規範。除了建立 Swagger 檔案之外，我們也會建立相關的用途說明文件/ 高層級文件，說明如何使用 API 執行特定工作。這項功能可建立版本並自動產生，以免手動操作，產生的 Markdown 檔案可做為網頁代管或匯出為 PDF。

第二階段將說明 Spider、Autoupdate、Context、Status、Search API，並透過 Markdown 檔案建立相關用途文章。

最後階段將涵蓋未記錄說明的 API 和相關用途。在最後一個月，我還打算涵蓋需要叫用多個 API 元件才能執行工作的用途。