Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- OWASP Foundation
- Redattore tecnico:
- sshniro
- Nome del progetto:
- Miglioramento della documentazione dell'API ZAP
- Durata del progetto:
- Durata standard (3 mesi)
Project description
ZAP ha un'API estremamente potente che ci consente di fare quasi tutto ciò che è possibile tramite l'interfaccia desktop. Tuttavia, per utilizzare in modo efficace le API, è necessaria una buona conoscenza della UI. Questo perché la maggior parte delle API è direttamente correlata all'interfaccia utente del proxy ZA. Un documento sull'API e sull'utilizzo/ sul caso d'uso ben documentato può aiutarti a superare questo collo di bottiglia durante la prova delle API.
Al momento, i documenti dell'API vengono generati automaticamente, forniscono poche informazioni sui parametri coinvolti e offrono meno opportunità alla community di contribuire alla documentazione dell'API. Inoltre, l'interfaccia utente basata sul web (versione desktop) utilizzata all'interno di ZAP utilizza anche l'elenco di API generato automaticamente per l'invocazione. Questa interfaccia utente di chiamata dell'API basata sul web fornisce inoltre informazioni molto limitate su come utilizzare l'API e cosa aspettarsi quando la chiami ( ad es. i risultati dell'API). Pertanto, in questa proposta, suggerisco un nuovo approccio per la documentazione delle API.
L'idea è ricreare i documenti API con le specifiche Open API 3. Open API fornisce un framework comune per sviluppatori, tester e dev-ops per creare, gestire e testare le API. Le specifiche OpenAPI completate per ZAP possono essere utilizzate per generare automaticamente i file swagger. I file Swagger possono essere integrati nell'interfaccia utente dell'applicazione web (app desktop) di ZAP per fornire agli utenti un client di test API completo.
Oltre alla documentazione dell'API, ho intenzione di utilizzare il convertitore swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) per generare i documenti dell'API in formato Markdown. Questo approccio (swagger-converter) semplifica la generazione di documentazione aggiornata delle API RESTful combinando la documentazione scritta a mano con la documentazione dell'API generata automaticamente prodotta da Swagger. I risultati saranno simili a quelli indicati nella documentazione dell'API di GitHub. (https://developer.github.com/v3/). Questo documento scritto a mano conterrà documenti di alto livello che spiegano come utilizzare le API per eseguire una determinata attività. Ad esempio, una scansione dell'API Spider è un'attività che richiede molto tempo e l'utente deve eseguire continuamente il polling dell'API per conoscere il relativo stato. Pertanto, questi documenti di alto livello illustrano le API da utilizzare per eseguire un'azione e rimandano ai documenti swagger generati automaticamente per ulteriori letture.
In ZA proxy sono state implementate oltre 380 API. Sto proponendo inizialmente di documentare tutte le API con una descrizione e informazioni sui parametri, le risposte di successo e di errore delle API. È già stato eseguito un POC di esempio e puoi trovare ulteriori dettagli nella proposta collegata.
Il periodo di tre mesi sarà suddiviso in tre fasi. Nella prima fase verranno create le specifiche Open API per Active Scan e le API di base (oltre 150). Parallelamente alla creazione dei file swagger, verranno creati anche la documentazione relativa ai casi d'uso e i documenti di alto livello su come utilizzare le API per eseguire attività specifiche. È possibile eseguire il controllo delle versioni e generare automaticamente le modifiche per rimuovere il lavoro manuale. Inoltre, i file di Markdown possono essere ospitati come pagine web o esportati come PDF.
La seconda fase riguarderà la documentazione delle API Spider, Aggiornamento automatico, Contesto, Stato e Ricerca e la creazione degli articoli sui casi d'uso pertinenti tramite file Markdown.
La fase finale riguarderà le altre API non documentate e i relativi casi d'uso pertinenti. Nell'ultimo mese, ho in programma di trattare anche i casi d'uso che richiedono l'invocazione di più componenti dell'API per eseguire un'attività.