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. Cependant, 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 offrent moins d'opportunité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 à quoi vous devez vous attendre lors de l'appel des API ( par exemple, résultats de l'API). 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, aux testeurs et aux développeurs d'opérations de développement pour créer, gérer et tester des API. Les spécifications complètes de l'API Open API 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) 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 (convertisseur Swagger) simplifie la génération d'une documentation actualisée sur l'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 généraux expliquant comment les API doivent être utilisées pour effectuer une certaine tâche. Par exemple, une analyse de l'API Spider est une tâche de longue durée, et l'utilisateur doit interroger en permanence l'API pour connaître son état. Par conséquent, ces documents généraux expliquent quelles API utiliser pour effectuer une action et renvoient vers les documents swagger générés automatiquement pour plus d'informations.
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. Vous avez déjà effectué 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 consiste à créer les spécifications de l'API Open API pour Active Scan, les API principales (plus de 150). Parallèlement à la création des fichiers Swagger, une documentation de cas d'utilisation pertinente et des documents de haut niveau expliquant comment utiliser les API pour effectuer des tâches spécifiques seront également créés. Il peut être géré par version et généré automatiquement pour supprimer les tâches manuelles. Les fichiers Markdown peuvent ê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 également d'aborder les cas d'utilisation qui nécessitent d'appeler plusieurs composants d'API pour effectuer une tâche.