Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Fundación OWASP
- Redactor técnico:
- sshniro
- Nombre del proyecto:
- Mejora de la documentación de la API de ZAP
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
ZAP tiene una API extremadamente potente que nos permite hacer casi todo lo que es posible a través de la interfaz de escritorio. Sin embargo, para usar las APIs de manera eficaz, es necesario comprender bien la IU. Esto se debe a que la mayoría de las APIs se correlacionan directamente con la interfaz de usuario del proxy de ZA. Una API bien documentada y un documento de caso de uso/ uso pueden ayudar a superar este cuello de botella cuando se prueban las APIs.
Actualmente, los documentos de la API se generan automáticamente, proporcionan poca información sobre los parámetros involucrados y ofrecen menos oportunidades para que la comunidad contribuya con la documentación de la API. Además, la IU basada en la Web (versión para computadoras) que se usa dentro de ZAP también utiliza la lista de API generada automáticamente para la invocación. Esta IU de invocación de API basada en la Web también proporciona información muy limitada sobre cómo usar la API y qué esperar cuando se invoquen las APIs ( p. ej., resultados de la API). Por lo tanto, en esta propuesta, sugiero un nuevo enfoque para documentar las APIs.
La idea es volver a crear los documentos de la API con las especificaciones de Open API 3. La API abierta proporciona un framework común para que desarrolladores, verificadores y desarrolladores de operaciones de desarrollo compilen, mantengan y prueben APIs. Las especificaciones de Open API completadas para ZAP se pueden usar para generar automáticamente los archivos de Swagger. Los archivos de Swagger se pueden integrar en la IU de la aplicación web (app para computadoras de escritorio) de ZAP para proporcionar a los usuarios un cliente de prueba de API enriquecido.
Además de la documentación de la API, planeo usar el convertidor swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) para generar la documentación de la API en formato Markdown. Este enfoque (swagger-converter) simplifica la generación de documentación de API RESTful actualizada combinando la documentación escrita a mano con la documentación de API generada automáticamente que produce Swagger. Los resultados serán similares a la documentación de la API de GitHub. (https://developer.github.com/v3/). Este documento escrito a mano tendrá documentos de alto nivel que explicarán cómo se deben usar las APIs para realizar una tarea determinada. Por ejemplo, un análisis de la API de Spider es una tarea de larga duración, y el usuario debe sondear la API de forma continua para conocer su estado. Por lo tanto, estos documentos de alto nivel analizarán qué APIs se usarán para realizar una acción y señalarán los documentos de Swagger generados automáticamente para su lectura adicional.
Se implementó una cantidad total de más de 380 APIs en el proxy de ZA. En un principio, propongo documentar todas las APIs con una descripción para ellas, información sobre los parámetros y las respuestas de éxito y fracaso de las APIs. Ya se realizó una POC de muestra, y puedes ver detalles adicionales en la propuesta vinculada.
El período de tres meses se dividirá en tres fases. En la primera fase, se crearán las especificaciones de Open API para Active Scan y Core APIs (más de 150). Además de la creación de los archivos de Swagger, también se crearán la documentación del caso de uso relevante y los documentos de alto nivel sobre cómo usar las APIs para realizar tareas específicas. Se puede crear un control de versiones y generarse automáticamente para quitar el trabajo manual, y los archivos de Markdown se pueden alojar como páginas web o exportarse como PDF.
La segunda fase cubrirá la documentación de las APIs de Spider, Autoupdate, Context, Status y Search, y la creación de artículos de casos de uso relevantes a través de archivos de Markdown.
En la fase final, se abordará el resto de las APIs no documentadas y sus casos de uso relevantes. En el último mes, también planeo abordar los casos de uso que requieren invocar varios componentes de API para realizar una tarea.