本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- OWASP 基础
- 技术文档工程师：
- sshniro
- 项目名称：
- 增强了 ZAP API 文档
- 项目时长：
- 标准时长（3 个月）
Project description
ZAP 拥有强大的 API，可让我们通过桌面界面执行几乎所有可能的操作。不过，要想有效使用这些 API，您需要对界面有充分的了解。这是因为大多数 API 都与 ZA 代理的界面直接相关。在试用 API 时，API 文档和使用/ 用例文档的详尽程度有助于克服这一瓶颈。
目前，API 文档是自动生成的，提供的有关相关参数的信息很少，并且社区贡献 API 文档的机会较少。此外，ZAP 中使用的基于 Web 的界面（桌面版）也使用自动生成的 API 列表进行调用。这个基于网络的 API 调用界面还提供了非常有限的信息，说明如何使用该 API，以及在调用 API 时会发生什么情况（例如，API 结果）。因此，在此提案中，我建议采用一种新的方法来记录 API。
方法是使用 OpenAPI 3 规范重新创建 API 文档。Open API 为开发者、测试人员和开发运维团队提供了一个通用框架，以便构建、维护和测试 API。为 ZAP 完成的 OpenAPI 规范可用于自动生成 Swagger 文件。Swagger 文件可以集成到 ZAP 的 Web 应用（桌面应用）界面中，为用户提供丰富的 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，您可以在关联的提案中查看更多详细信息。
这三个月的时间将分为三个阶段。第一阶段将为 Active Scan 和核心 API（150 多个）创建 Open API 规范。与创建 Swagger 文件同时，我们还将创建有关如何使用 API 执行特定任务的相关用例文档/ 概要文档。您可以对其进行版本控制并自动生成，以免手动操作，生成的 Markdown 文件可以作为网页托管或导出为 PDF。
第二阶段将介绍如何记录 Spider、Autoupdate、Context、Status、Search API，以及如何通过 Markdown 文件创建相关的用例文章。
最后一个阶段将涵盖未记录的其余 API 及其相关用例。在下个月，我还计划介绍需要调用多个 API 组件才能执行任务的用例。