本页面包含“Google 文档季”接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- OWASP 基金会
- 技术文档工程师：
- sshniro
- 项目名称：
- ZAP API 文档的增强功能
- 项目时长：
- 标准时长（3 个月）
Project description
ZAP 拥有非常强大的 API，几乎可以让我们通过桌面界面完成所有工作。不过，为了有效使用 API，您需要充分了解界面。这是因为大多数 API 都与 ZA 代理的界面直接关联。试用 API 时，文档完备的 API 和用法/ 用例文档有助于克服此瓶颈。
目前，API 文档是自动生成的，提供的参数信息不多，而且社区为 API 文档贡献力量的机会减少了。此外，ZAP 内使用的基于网络的界面（桌面版本）也使用自动生成的 API 列表进行调用。这个基于网络的 API 调用界面还提供了非常有限的信息，说明如何使用该 API 以及调用 API 时预期会出现什么情况（例如，API 结果）。因此，在此方案中，我建议采用一种新方法来记录 API。
其想法是使用 Open API 3 规范重新创建 API 文档。Open API 为开发者、测试人员和开发运维人员提供了一个构建、维护和测试 API 的通用框架。完成后的 ZAP 的 Open API 规范可用于自动生成 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，可在关联的提案中查看其他详细信息。
这三个月的期限将分为三个阶段。第一阶段将创建主动扫描的 Open API 规范、核心 API（超过 150 个）。在创建 Swagger 文件的同时，还将创建有关如何使用 API 执行特定任务的相关用例文档/ 概要文档。该代码可以版本化和自动生成，以消除手动工作，并且产生的 Markdown 文件可以托管为网页或以 PDF 格式导出。
第二阶段将介绍如何记录 Spider、Autoupdate、Context、Status、Search API 以及通过 Markdown 文件创建相关的用例文章。
最后一个阶段将介绍其余未载明的 API 及其相关用例。在上个月，我还打算介绍需要调用多个 API 组件才能执行某项任务的用例。