Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Fondation OWASP
- Rédacteur technique:
- sshniro
- Nom du projet:
- Amélioration de la documentation sur l'API ZAP
- Durée du projet:
- Durée standard (3 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 de bureau. Toutefois, pour utiliser efficacement les API, une bonne compréhension de l'interface utilisateur est nécessaire. En effet, la plupart des API sont directement liées à l'interface utilisateur du proxy ZA. Une API bien documentée et un document d'utilisation/ de cas d'utilisation peuvent aider à contourner 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 donnent moins de possibilités à la communauté de contribuer à la documentation de l'API. De plus, l'interface utilisateur Web (version de bureau) utilisée dans 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 qui se passe lors de l'appel des API ( résultats de l'API, par exemple). Par conséquent, dans cette proposition, je suggère une nouvelle approche pour documenter les fonctionnalités de l'API.
L'idée est de recréer les documents d'API avec les spécifications Open API 3. Les API ouvertes fournissent un framework commun aux développeurs, testeurs et équipes DevOps pour créer, gérer et tester des API. Les spécifications complètes des API ouvertes 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 afin de fournir aux utilisateurs un client de test d'API enrichi.
Outre la documentation de l'API, j'envisage d'utiliser le convertisseur swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) pour générer les documents d'API au format Markdown. Cette approche simplifie la génération d'une documentation à jour pour les API RESTful en combinant une documentation manuscrite et une documentation d'API générée automatiquement par Swagger. Les résultats seront semblables à ceux de la documentation de l'API GitHub. (https://developer.github.com/v3/). Ce document manuscrit contient des documents de haut niveau expliquant comment les API doivent être utilisées pour effectuer une certaine tâche. Par exemple, une analyse d'API Spider est une tâche de longue durée, et l'utilisateur doit interroger en permanence l'API pour connaître l'état de l'API. Par conséquent, ces documents de haut niveau évoquent les API à utiliser pour effectuer une action et renvoient vers les documents fantaisistes 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 les paramètres, ainsi que les réponses de réussite et d'échec des API. Nous avons déjà réalisé un exemple de démonstration de faisabilité. Vous trouverez des informations supplémentaires dans la proposition associée.
Cette période de trois mois sera divisée en trois phases. La première phase consistera à créer les spécifications de l'API Open Scan pour les API Active Scan, Core API (plus de 150). Parallèlement à la création des fichiers swagger, la documentation pertinente et les documents généraux sur la façon d'utiliser les API pour effectuer des tâches spécifiques seront créés. Il peut être géré par version et généré automatiquement pour supprimer le travail manuel. Les fichiers Markdown peuvent ensuite être hébergés en tant que pages Web ou exportés au format PDF.
La deuxième phase portera sur la documentation des API Spider, Autoupdate, Context, Status et Search, ainsi que sur la création d'articles de cas d'utilisation pertinents via des fichiers Markdown.
La dernière phase portera sur les autres API non documentées et leurs cas d'utilisation pertinents. Au cours du dernier mois, je prévois aussi d'aborder les cas d'utilisation qui nécessitent d'appeler plusieurs composants d'API pour effectuer une tâche.