This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- OWASP Foundation
- Technical writer:
- sshniro
- Project name:
- Enhancement of the ZAP API Documentation
- Project length:
- Standard length (3 months)
Project description
ZAP has an extremely powerful API that allows us to do nearly everything that possible via the desktop interface. However, to effectively use the APIs, a good understanding of the UI is needed. This is because most of the APIs directly correlate to the user interface of the ZA proxy. A well-documented API and usage/ use-case document can assist in overcoming this bottleneck when trying out the APIs.
Currently, the API documents are autogenerated, provides little information regarding the parameters involved, and gives less opportunity for the community to contribute to the API documentation. Additionally, the web-based UI (desktop version) used inside the ZAP also uses the autogenerated API list for invocation. This web-based API invocation UI also provides very limited information on how to use the API and what to expect when invoking the APIs ( Eg- API results). Therefore in this proposal, I'm suggesting a new approach for documenting the API's.
The idea is to re-create the API documents with Open API 3 Specifications. Open API provides a common framework for developers, testers, and dev-ops to build, maintain and test APIs. The completed Open API specs for ZAP can be used to auto-generate the swagger files. The Swagger files can be integrated into ZAP’s web application (Desktop App) UI to provide a rich API testing client to the users.
Apart from the API documentation, I'm planning to use the swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) converter to generate the API docs in Markdown format. This approach (swagger-converter) simplifies the generation of up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation produced by Swagger. The results will be similar to Github’s API documentation. (https://developer.github.com/v3/). This handwritten doc will have high-level documents explaining how the APIs should be used in order to perform a certain task. For example, a Spider API scan is a long-running task and the user should continuously poll the API to know the status of the API. Hence these high-level documents will discuss which APIs to be used to perform an action and point to the autogenerated swagger documents for further read.
A total number of 380+ APIs have been implemented in ZA proxy. I'm initially proposing to document all the APIs with a description to the APIs, information regarding the parameters, success, and failure responses of the APIs. Already a sample POC has been done, and additional details can be seen in the linked proposal.
The three month period will be divided into three phases. The first phase will create the Open API specs for Active Scan, Core APIs (150+). In parallel with creating the swagger files, the relevant use-case documentation/ high-level documents on how to use the APIs to perform specific tasks will be also created. This can be versioned and autogenerated to remove manual work and resulted markdown files can be hosted as webpages or exported as PDF.
The second phase will cover documenting Spider, Autoupdate, Context, Status, Search APIs and creating the relevant use case articles via Markdown files.
The final phase will cover the rest of the undocumented APIs and their relevant use-cases. In the last month, I’m planning to also cover use cases that require invoking multiple API components to perform a task.