Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- OWASP Foundation
- Technischer Redakteur:
- sshniro
- Projektname:
- Verbesserung der ZAP API-Dokumentation
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
ZAP verfügt über eine äußerst leistungsstarke API, mit der wir fast alles tun können, was über die Desktop-Oberfläche möglich ist. Für die 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 zusammenhängen. Eine gut dokumentierte API und ein Nutzungs-/Anwendungsfalldokument können dabei helfen, diesen Engpass beim Testen der APIs zu überwinden.
Derzeit werden die API-Dokumente automatisch generiert, bieten wenig Informationen zu den beteiligten Parametern und bieten der Community weniger Möglichkeiten, zur API-Dokumentation beizutragen. Außerdem verwendet die webbasierte Benutzeroberfläche (Desktopversion), die in der ZAP verwendet wird, auch die automatisch generierte API-Liste zum Aufrufen. Diese webbasierte API-Aufruf-Benutzeroberfläche bietet auch nur sehr begrenzte Informationen zur Verwendung der API und zu den zu erwartenden Ergebnissen ( z. B. API-Ergebnisse). Daher schlage ich in diesem Vorschlag einen neuen Ansatz zur Dokumentation der APIs vor.
Die API-Dokumente sollen mit OpenAPI 3-Spezifikationen neu erstellt werden. Open API bietet Entwicklern, Testern und Dev-Ops ein gemeinsames Framework 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 Webanwendung (Desktop-Anwendung) von ZAP eingebunden werden, um den Nutzern einen umfassenden API-Testclient zur Verfügung zu stellen.
Neben der API-Dokumentation möchte ich den Konverter „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 manuell erstellte Dokumentation mit automatisch generierter API-Dokumentation von Swagger kombiniert wird. Die Ergebnisse ähneln der API-Dokumentation von GitHub. (https://developer.github.com/v3/). Dieses handgeschriebene Dokument enthält allgemeine Dokumente, in denen erklärt wird, wie die APIs verwendet werden sollten, um eine bestimmte Aufgabe auszuführen. Ein Spider API-Scan ist beispielsweise eine lang andauernde Aufgabe und der Nutzer sollte die API kontinuierlich abfragen, um den Status der API zu erfahren. Daher werden in diesen allgemeinen Dokumenten die APIs beschrieben, die für die Ausführung einer Aktion verwendet werden, und es wird auf die automatisch generierten Swagger-Dokumente verwiesen.
In ZA Proxy wurden insgesamt mehr als 380 APIs implementiert. Ich schlage vor, alle APIs mit einer Beschreibung der APIs, Informationen zu den Parametern sowie zu erfolgreichen und fehlgeschlagenen Antworten der APIs zu dokumentieren. Es wurde bereits ein Beispiel-POC erstellt. Weitere Informationen finden Sie im verlinkten Vorschlag.
Der Dreimonatszeitraum wird in drei Phasen unterteilt. In der ersten Phase werden die OpenAPI-Spezifikationen für Active Scan, Core APIs (ab 150) erstellt. Parallel zur Erstellung der Swagger-Dateien werden auch die relevante Dokumentation für den Anwendungsfall/ die übergeordneten Dokumente zur Verwendung der APIs für die Ausführung bestimmter Aufgaben erstellt. Diese können versioniert und automatisch generiert werden, um manuelle Arbeiten zu entfernen. Die resultierenden Markdown-Dateien können als Webseiten gehostet oder als PDF exportiert werden.
In der zweiten Phase geht es um die Dokumentation von Spider, Autoupdate, Context, Status, Search APIs und das Erstellen der relevanten Artikel zu Anwendungsfällen über Markdown-Dateien.
In der letzten Phase werden die restlichen nicht dokumentierten APIs und ihre relevanten Anwendungsfälle abgedeckt. Im letzten Monat werde ich auch Anwendungsfälle behandeln, bei denen zum Ausführen einer Aufgabe mehrere API-Komponenten aufgerufen werden müssen.