Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.
Riepilogo del progetto
- Organizzazione open source:
- Fondazione 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 praticamente tutto ciò che è possibile 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 è correlata direttamente all'interfaccia utente del proxy ZA. Un'API ben documentata e un documento di utilizzo/ caso d'uso possono aiutare a superare questo collo di bottiglia quando si provano le API.
Attualmente, i documenti dell'API sono 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 dello ZAP utilizza anche l'elenco API generato automaticamente per le chiamate. 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 es. 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 sfavorevoli. I file Swagger possono essere integrati nell'interfaccia utente dell'applicazione web (app desktop) di ZAP per fornire agli utenti un client di test avanzato dell'API.
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 di documentazione aggiornata relativa all'API RESTful combinando la documentazione scritta a mano con quella relativa all'API generata automaticamente e prodotta da Swagger. I risultati saranno simili alla documentazione dell'API di GitHub. (https://developer.github.com/v3/). Questo documento scritto a mano contiene 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. Questi documenti di alto livello discuteranno delle API da utilizzare per eseguire un'azione e rimanderanno ai documenti spavaldi generati automaticamente per ulteriori letture.
Nel proxy ZA sono state implementate oltre 380 API. Inizialmente propongo di documentare tutte le API con una descrizione delle API e 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 di base (oltre 150). Parallelamente alla creazione dei file spavaldi, verrà creata 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 tratterà 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à.