Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Fundación OWASP
- Escritor 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 posible a través de la interfaz para computadoras de escritorio. Sin embargo, para usar las APIs de manera efectiva, se necesita una buena comprensión de 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 o 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 a la comunidad de contribuir a 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 usa la lista de APIs 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 invocan ( 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 API abierta 3. La API abierta proporciona un marco de trabajo común para que los desarrolladores, verificadores y DevOps puedan compilar, mantener y probar APIs. Las especificaciones completas de Open API para ZAP se pueden usar para generar automáticamente los archivos de swagger. Los archivos Swagger pueden integrarse en la IU de aplicación web (aplicación para computadoras de escritorio) de ZAP para proporcionar a los usuarios un cliente de prueba de API enriquecida.
Además de la documentación de la API, quiero usar el convertidor de swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) para generar los documentos de la API en formato Markdown. Este enfoque (convertidor de swagger) simplifica la generación de documentación actualizada de la API de RESTful, ya que combina la documentación escrita a mano con la documentación de la API generada de forma automática producida por Swagger. Los resultados serán similares a los de la documentación de la API de GitHub. (https://developer.github.com/v3/). Este documento escrito a mano tendrá documentos de alto nivel en los que se explica 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 consultar continuamente la API para conocer su estado. Por lo tanto, en estos documentos de alto nivel, se analizarán las APIs que se deben usar para realizar una acción y se indicarán los documentos de swagger generados automáticamente para obtener más información.
Se implementaron una cantidad total de más de 380 APIs en el proxy de ZA. Inicialmente, propongo documentar todas las APIs con una descripción de ellas, información sobre los parámetros y respuestas de éxito y error de las APIs. Ya se realizó un PDC de muestra y se pueden ver detalles adicionales en la propuesta vinculada.
Este período se dividirá en tres fases. La primera fase creará las especificaciones de la API abierta para Active Scan, Core API (más de 150). En paralelo con la creación de los archivos swagger, también se crearán la documentación de caso de uso relevante y los documentos de alto nivel sobre cómo utilizar las API para realizar tareas específicas. Se puede controlar el control de versiones y generarse automáticamente para quitar el trabajo manual, y los archivos de Markdown resultantes se pueden alojar como páginas web o exportarse como PDF.
La segunda fase abarcará la documentación de Spider, Autoupdate, Context, Status y Search APIs y la creación de artículos de casos de uso relevantes a través de archivos Markdown.
En la fase final, se abordarán el resto de las APIs no documentadas y sus casos de uso relevantes. En el último mes, también deseo abordar casos de uso que requieran invocar varios componentes de API para realizar una tarea.