Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- OWASP-Stiftung
- Technischer Redakteur:
- sshniro
- Projektname:
- Verbesserung der ZAP API-Dokumentation
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
ZAP verfügt über eine äußerst leistungsstarke API, mit der wir nahezu alle Vorgänge über die Desktop-Benutzeroberfläche durchführen können. Für eine effektive Nutzung der APIs sind jedoch gute Kenntnisse der Benutzeroberfläche erforderlich. Das liegt daran, dass die meisten APIs direkt mit der Benutzeroberfläche des ZA-Proxys korrelieren. Eine gut dokumentierte API- und Nutzungs-/Anwendungsfalldokumentation kann helfen, diesen Engpass beim Testen der APIs zu überwinden.
Derzeit werden die API-Dokumente automatisch generiert, enthalten nur wenige Informationen zu den beteiligten Parametern und die Community gibt weniger Gelegenheit, einen Beitrag zur API-Dokumentation zu leisten. Darüber hinaus verwendet die webbasierte Benutzeroberfläche (Desktopversion), die im ZAP verwendet wird, auch die automatisch generierte API-Liste für den Aufruf. Diese webbasierte Benutzeroberfläche für API-Aufrufe bietet außerdem sehr begrenzte Informationen zur Verwendung der API und dazu, was beim Aufrufen der APIs zu erwarten ist ( z. B. API-Ergebnisse). Daher empfehle ich in diesem Vorschlag einen neuen Ansatz zur Dokumentation der APIs.
Die Idee ist, die API-Dokumente mit den OpenAPI 3-Spezifikationen neu zu erstellen. Open API bietet ein gemeinsames Framework für Entwickler, Tester und DevOps zum Erstellen, Verwalten und Testen von APIs. Die fertigen OpenAPI-Spezifikationen für ZAP können verwendet werden, um die Swagger-Dateien automatisch zu generieren. Die Swagger-Dateien können in die Webanwendungs-UI (Desktop-App) von ZAP integriert werden, um den Nutzern einen umfangreichen API-Testclient bereitzustellen.
Abgesehen von der API-Dokumentation möchte ich den Konvertierunger „swaggerToMarkdown“ (https://github.com/Swagger2Markup/swagger2markup) verwenden, um die API-Dokumente im Markdown-Format zu generieren. Dieser Ansatz (swagger-converter) vereinfacht die Erstellung einer aktuellen RESTful API-Dokumentation, indem handgeschriebene Dokumentation mit automatisch generierter API-Dokumentation von Swagger kombiniert wird. Die Ergebnisse ähneln der API-Dokumentation von GitHub. (https://developer.github.com/v3/). Dieses handschriftliche Dokument enthält übergeordnete Dokumente, in denen erklärt wird, wie die APIs für eine bestimmte Aufgabe verwendet werden sollten. Beispiel: Ein Spider API-Scan ist eine Aufgabe mit langer Ausführungszeit und der Nutzer sollte die API kontinuierlich abfragen, um den Status der API zu ermitteln. Daher wird in diesen übergeordneten Dokumenten erläutert, welche APIs zum Ausführen einer Aktion verwendet werden sollen, und verweisen auf die automatisch generierten Swagger-Dokumente zum weiteren Lesen.
Im ZA-Proxy wurden mehr als 380 APIs implementiert. Ich schlage zunächst vor, alle APIs mit einer Beschreibung der APIs, Informationen zu den Parametern, den Erfolgs- und Fehlerantworten der APIs zu dokumentieren. Es wurde bereits ein Beispiel-POC erstellt. Im verknüpften Angebot sind weitere Details zu sehen.
Der Zeitraum von drei Monaten unterteilt sich in drei Phasen. In der ersten Phase werden die Open API-Spezifikationen für Active Scan, Core APIs (über 150) erstellt. Parallel zur Erstellung der Swagger-Dateien werden auch die relevante Anwendungsfalldokumentation und übergeordnete Dokumente zur Verwendung der APIs für bestimmte Aufgaben erstellt. Diese Datei kann versioniert und automatisch generiert werden, um manuelle Arbeit zu vermeiden. Die gefundenen Markdown-Dateien können als Webseiten gehostet oder als PDF exportiert werden.
In der zweiten Phase werden Spider, Autoupdate, Kontext, Status und Such-APIs dokumentiert und relevante Anwendungsfallartikel über Markdown-Dateien erstellt.
In der letzten Phase werden die übrigen nicht dokumentierten APIs und ihre relevanten Anwendungsfälle behandelt. Im letzten Monat möchte ich auch Anwendungsfälle behandeln, bei denen zur Ausführung einer Aufgabe mehrere API-Komponenten aufgerufen werden müssen.