このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソース組織:
- OWASP Foundation
- テクニカル ライター:
- 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 つのフェーズに分かれています。最初のフェーズでは、アクティブ スキャンのコア API（150 個以上）の Open API 仕様を作成します。Swagger ファイルの作成と並行して、API を使用して特定のタスクを実行する方法に関する関連するユースケースのドキュメント/ 概要ドキュメントも作成されます。バージョン管理と自動生成により手作業を排除でき、生成されたマークダウン ファイルをウェブページとしてホストしたり、PDF としてエクスポートしたりできます。
2 つ目のフェーズでは、Spider、Autoupdate、Context、Status、Search API のドキュメント化と、Markdown ファイルを使用して関連するユースケースの記事を作成します。
最終フェーズでは、ドキュメント化されていない残りの API とそれらの関連するユースケースについて説明します。先月は、タスクを実行するために複数の API コンポーネントを呼び出す必要があるユースケースについても説明する予定です。