Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Piattaforma OWASP
- Technical writer:
- Sshniro
- Nome 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ò tramite l'interfaccia desktop. Tuttavia, per utilizzare le API in modo efficace, è necessaria una buona comprensione dell'interfaccia utente. Questo perché la maggior parte delle API è direttamente correlata all'interfaccia utente del proxy ZA. Un'API ben documentata e un documento di utilizzo/ casi d'uso possono aiutare a superare questo collo di bottiglia quando si provano le API.
Attualmente, i documenti dell'API vengono generati automaticamente, forniscono poche informazioni sui parametri interessati e offrono meno opportunità alla community di contribuire alla documentazione dell'API. Inoltre, l'interfaccia utente basata sul web (versione desktop) utilizzata all'interno dello ZAP utilizza per le chiamate anche l'elenco di API generato automaticamente. Questa UI di chiamata API basata sul web fornisce inoltre informazioni molto limitate su come utilizzare l'API e cosa aspettarsi quando si richiamano le API ( ad esempio, i risultati delle API). Pertanto, in questa proposta, suggerirei un nuovo approccio per documentare le API.
L'idea è ricreare i documenti dell'API con le specifiche Open API 3. L'API aperta fornisce un framework comune a sviluppatori, tester e sviluppatori per creare, gestire e testare le API. Le specifiche complete dell'API Open per ZAP possono essere utilizzate per generare automaticamente i file spavaldo. 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 avanzato.
Oltre alla documentazione dell'API, ho in programma di utilizzare il convertitore swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) per generare documenti API in formato Markdown. Questo approccio (swagger-converter) semplifica la generazione della documentazione aggiornata dell'API RESTful combinando la documentazione scritta a mano con la documentazione dell'API generata automaticamente prodotta da Swagger. I risultati saranno simili a quelli riportati 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à a lunga esecuzione e l'utente deve eseguire continuamente il polling dell'API per conoscerne lo stato. Quindi, in questi documenti di alto livello verranno illustrate le API da utilizzare per eseguire un'azione e verranno indirizzati i documenti spavaldi generati automaticamente per ulteriori approfondimenti.
Nel proxy ZA sono state implementate un numero totale di oltre 380 API. Inizialmente propongo di documentare tutte le API con una descrizione delle API, informazioni sui parametri e le risposte di successo e errore delle API. È già stato creato un POC di esempio ed è possibile visualizzare ulteriori dettagli nella proposta collegata.
Il periodo di tre mesi sarà suddiviso in tre fasi. La prima fase creerà le specifiche Open API per Active Scan, API principali (oltre 150). Parallelamente alla creazione dei file spavaldi, verranno creati anche la documentazione dei casi d'uso/ documenti di alto livello pertinenti su come utilizzare le API per eseguire attività specifiche. Questo può essere sottoposto al controllo delle versioni e generato automaticamente per rimuovere il lavoro manuale e i relativi file di markdown possono essere ospitati come pagine web o esportati come PDF.
La seconda fase riguarderà la documentazione di Spider, Autoupdate, Context, Status, Search API e la creazione degli articoli dei casi d'uso pertinenti tramite i file Markdown.
La fase finale riguarderà il resto delle 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 il richiamo di più componenti dell'API per eseguire un'attività.