本页面包含有关 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 格式导出。
第二阶段将介绍如何记录“蜘蛛”程序、自动更新、上下文、状态、搜索 API，以及如何通过 Markdown 文件创建相关的用例文章。
在最后一个阶段，我们将介绍其余未载明的 API 及其相关用例。上个月，我还打算介绍需要调用多个 API 组件才能执行某项任务的用例。