Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel 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 extrem leistungsstarke API, mit der wir fast alles tun können, was über die Desktop-Oberfläche möglich ist. Für eine effektive Nutzung der APIs ist jedoch ein gutes Verständnis der Benutzeroberfläche erforderlich. Das liegt daran, dass die meisten APIs direkt mit der Benutzeroberfläche des ZA-Proxys korrelieren. Ein gut dokumentiertes API- und Nutzungs-/Anwendungsfalldokument kann helfen, diesen Engpass beim Testen der APIs zu überwinden.
Derzeit werden die API-Dokumente automatisch generiert, enthalten wenig Informationen zu den beteiligten Parametern und bieten der Community weniger Gelegenheit, einen Beitrag zur API-Dokumentation zu leisten. Darüber hinaus verwendet die webbasierte Benutzeroberfläche (Desktopversion), die in der ZAP verwendet wird, auch die automatisch generierte API-Liste für den Aufruf. Diese webbasierte API-Aufruf-Benutzeroberfläche bietet auch sehr begrenzte Informationen zur Verwendung der API und dazu, was beim Aufrufen der APIs zu erwarten ist ( z. B. API-Ergebnisse). Daher schlage ich in diesem Vorschlag einen neuen Ansatz zur Dokumentation der APIs vor.
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 Benutzeroberfläche der ZAP-Webanwendung (Desktop-App) integriert werden, um den Nutzern einen umfangreichen API-Testclient bereitzustellen.
Neben der API-Dokumentation habe ich vor, den Konvertierungsdienst „swaggerToMarkdown“ (https://github.com/Swagger2Markup/swagger2markup) zu verwenden, um die API-Dokumente im Markdown-Format zu generieren. Dieser Ansatz (swagger-converter) vereinfacht die Erstellung einer aktuellen RESTful API-Dokumentation, indem handschriftliche 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. Beispielsweise ist ein Spider-API-Scan eine lang andauernde Aufgabe und der Benutzer 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 auf die automatisch generierten Swagger-Dokumente zum weiteren Lesen verweisen.
Im ZA-Proxy wurden insgesamt über 380 APIs implementiert. Ich schlage zunächst vor, alle APIs mit einer Beschreibung der APIs, Informationen zu den Parametern sowie den Erfolgs- und Fehlerantworten der APIs zu dokumentieren. Es wurde bereits ein Beispiel-POC erstellt. Weitere Details finden Sie im verknüpften Angebot.
Der Zeitraum von drei Monaten wird in drei Phasen unterteilt. In der ersten Phase werden die OpenAPI-Spezifikationen für Active Scan und Core APIs (über 150) erstellt. Parallel zur Erstellung der Swagger-Dateien werden auch die relevante Anwendungsfalldokumentation sowie ü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 Ergebnisse der Markdown-Dateien können als Webseiten gehostet oder als PDF exportiert werden.
In der zweiten Phase werden Spider, Autoupdate, Context, Status und Search APIs dokumentiert. Außerdem werden relevante Artikel über Markdown-Dateien erstellt.
In der letzten Phase werden die restlichen nicht dokumentierten APIs und ihre relevanten Anwendungsfälle behandelt. Im letzten Monat werde ich auch Anwendungsfälle abdecken, bei denen mehrere API-Komponenten zum Ausführen einer Aufgabe aufgerufen werden müssen.