Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.
Résumé du projet
- Organisation Open Source:
- Fondation OWASP
- Rédacteur technique:
- sshniro
- Nom du projet:
- Amélioration de la documentation de l'API ZAP
- Durée du projet:
- Durée standard (trois mois)
Project description
ZAP dispose d'une API extrêmement puissante qui nous permet de faire presque tout ce qui est possible via l'interface pour ordinateur. Toutefois, pour utiliser efficacement les API, vous devez bien comprendre l'interface utilisateur. En effet, la plupart des API sont directement liées à l'interface utilisateur du proxy ZA. Une API bien documentée et un document de cas d'utilisation/ d'utilisation peuvent aider à surmonter ce goulot d'étranglement lors du test des API.
Actuellement, les documents de l'API sont générés automatiquement, fournissent peu d'informations sur les paramètres impliqués et offrent moins de possibilités à la communauté de contribuer à la documentation de l'API. En outre, l'interface utilisateur Web (version pour ordinateur) utilisée dans le ZAP utilise également la liste d'API générée automatiquement pour les appels. Cette interface utilisateur d'appel d'API basée sur le Web fournit également des informations très limitées sur l'utilisation de l'API et sur ce à quoi vous attendre lorsque vous l'appelez ( par exemple, les résultats de l'API). Par conséquent, dans cette proposition, je suggère une nouvelle approche pour documenter les API.
L'idée est de recréer les documents de l'API avec les spécifications OpenAPI 3. Open API fournit un framework commun permettant aux développeurs, aux testeurs et aux équipes de développement (DevOps) de créer, gérer et tester des API. Les spécifications Open API finalisées pour ZAP peuvent être utilisées pour générer automatiquement les fichiers Swagger. Les fichiers Swagger peuvent être intégrés à l'interface utilisateur de l'application Web (application de bureau) de ZAP pour fournir aux utilisateurs un client de test d'API riche.
En plus de la documentation de l'API, je prévois d'utiliser le convertisseur swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) pour générer la documentation de l'API au format Markdown. Cette approche (swagger-converter) simplifie la génération de documentation à jour sur les API REST en combinant la documentation écrite à la main avec la documentation d'API générée automatiquement par Swagger. Les résultats seront semblables à la documentation de l'API GitHub. (https://developer.github.com/v3/). Ce document manuscrit contient des documents d'ordre général expliquant comment utiliser les API pour effectuer une tâche donnée. Par exemple, une analyse de l'API Spider est une tâche de longue durée. L'utilisateur doit interroger en continu l'API pour connaître son état. Par conséquent, ces documents d'ordre général indiquent les API à utiliser pour effectuer une action et pointent vers les documents swagger générés automatiquement pour en savoir plus.
Au total, plus de 380 API ont été implémentées dans le proxy ZA. Dans un premier temps, je propose de documenter toutes les API avec une description, des informations sur leurs paramètres, ainsi que les réponses de réussite et d'échec des API. Un exemple de POC a déjà été réalisé. Pour en savoir plus, consultez la proposition en lien.
La période de trois mois sera divisée en trois phases. La première phase consiste à créer les spécifications Open API pour Active Scan et les API principales (plus de 150). Parallèlement à la création des fichiers swagger, la documentation sur les cas d'utilisation pertinents/ les documents d'ordre général sur l'utilisation des API pour effectuer des tâches spécifiques sera également créée. Vous pouvez gérer les versions et générer automatiquement ce contenu pour vous épargner le travail manuel. Les fichiers Markdown générés peuvent être hébergés en tant que pages Web ou exportés au format PDF.
La deuxième phase consistera à documenter les API Spider, Autoupdate, Context, Status et Search, et à créer les articles sur les cas d'utilisation pertinents à l'aide de fichiers Markdown.
La phase finale couvrira le reste des API non documentées et leurs cas d'utilisation pertinents. Au cours du mois dernier, j'ai également prévu de couvrir les cas d'utilisation qui nécessitent d'appeler plusieurs composants d'API pour effectuer une tâche.