このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- OWASP 財団
- テクニカル ライター:
- sshniro
- プロジェクト名:
- ZAP API ドキュメントの機能強化
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
ZAP の非常に強力な API を使用すると、ほぼすべてをデスクトップ インターフェースから行うことができます。ただし、API を効果的に使用するには、UI を十分に理解している必要があります。これは、ほとんどの API が ZA プロキシのユーザー インターフェースと直接相関しているためです。適切に文書化された API と使用方法/ ユースケースのドキュメントは、API を試す際にこのボトルネックを克服する際に役立ちます。
現在、API ドキュメントは自動生成されており、関連するパラメータに関する情報はほとんど提供されていません。また、コミュニティが API ドキュメントに貢献する機会もあまりありません。また、ZAP 内で使用されるウェブベースの UI（パソコン版）でも、自動生成された API リストが呼び出しに使用されます。このウェブベースの API 呼び出し UI では、API の使用方法と API 呼び出しの際に想定される内容に関する情報（API の結果など）も非常に限定的に表示されます。そこで、この提案では、API を文書化するための新しいアプローチを提案します。
考え方としては、Open API 3 の仕様で API ドキュメントを再作成することです。Open API は、デベロッパー、テスター、DevOps が API を作成、保守、テストするための共通のフレームワークを提供します。完成した ZAP 用の Open API 仕様を使用して、swagger ファイルを自動生成できます。Swagger ファイルは、ZAP のウェブ アプリケーション（デスクトップ アプリ）UI に統合して、機能豊富な API テスト クライアントをユーザーに提供できます。
API ドキュメントとは別に、swaggerToMarkdown（https://github.com/Swagger2Markup/swagger2markup）コンバータを使用して、Markdown 形式の API ドキュメントを生成する予定です。このアプローチ（swagger-converter）を使用すると、手書きのドキュメントと Swagger によって生成された自動生成 API ドキュメントを組み合わせることで、最新の RESTful API ドキュメントの生成を簡素化できます。結果は GitHub の API ドキュメントと同様になります。（https://developer.github.com/v3/）。この手書きのドキュメントには、特定のタスクを実行するために API をどのように使用すべきかを説明するドキュメントがおおまかに示されています。たとえば、Spider API のスキャンは長時間実行タスクであるため、ユーザーは継続的に API をポーリングして API のステータスを確認する必要があります。したがって、これらの大まかなドキュメントでは、アクションの実行に使用する API について説明し、さらに読むために自動生成された swagger ドキュメントを取り上げます。
ZA プロキシには、合計 380 以上の API が実装されています。私はまず、API の説明、API のパラメータに関する情報、成功と失敗のレスポンスとともに、すべての API を文書化することを提案します。サンプルの POC がすでに作成されており、リンク先の提案で追加情報を確認できます。
この 3 か月の期間は 3 つのフェーズに分かれています。最初のフェーズでは、Active Scan の Core API（150 以上）の Open API 仕様を作成します。swagger ファイルの作成と並行して、関連するユースケースのドキュメントや、API を使用して特定のタスクを実行する方法の概要ドキュメントも作成します。バージョン管理と自動生成が可能で、手作業が不要になります。生成されたマークダウン ファイルはウェブページとしてホストしたり、PDF としてエクスポートしたりできます。
第 2 フェーズでは、Spider、自動更新、Context、Status、Search API を文書化し、マークダウン ファイルを使用して関連するユースケース記事を作成します。
最後のフェーズでは、ドキュメント化されていない API の残りと関連するユースケースを取り上げます。先月は、複数の API コンポーネントを呼び出してタスクを実行する必要がある場合のユースケースについても説明する予定です。