Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- {i>Foundation<i} OWASP
- Penulis teknis:
- sshniro
- Nama project:
- Peningkatan Dokumentasi ZAP API
- Durasi project:
- Durasi standar (3 bulan)
Project description
ZAP memiliki API yang sangat canggih yang memungkinkan kita melakukan hampir semua hal yang mungkin melalui antarmuka desktop. Namun, untuk menggunakan API secara efektif, pemahaman yang baik tentang UI diperlukan. Hal ini karena sebagian besar API secara langsung berkorelasi dengan antarmuka pengguna proxy ZA. API yang terdokumentasi dengan baik dan dokumen penggunaan/ kasus penggunaan dapat membantu mengatasi bottleneck ini saat mencoba API.
Saat ini, dokumen API dibuat secara otomatis, memberikan sedikit informasi terkait parameter yang terlibat, dan memberikan lebih sedikit peluang bagi komunitas untuk berkontribusi pada dokumentasi API. Selain itu, UI berbasis web (versi desktop) yang digunakan di dalam ZAP juga menggunakan daftar API yang dibuat secara otomatis untuk pemanggilan. UI pemanggilan API berbasis web ini juga memberikan informasi yang sangat terbatas tentang cara menggunakan API dan hal yang akan terjadi saat memanggil API ( misalnya, hasil API). Oleh karena itu, dalam proposal ini, saya menyarankan pendekatan baru untuk mendokumentasikan API.
Idenya adalah membuat ulang dokumen API dengan Spesifikasi Open API 3. Open API menyediakan framework umum bagi developer, penguji, dan dev-ops untuk mem-build, mengelola, dan menguji API. Spesifikasi Open API yang telah selesai untuk ZAP dapat digunakan untuk membuat file swagger secara otomatis. File Swagger dapat diintegrasikan ke dalam UI aplikasi web (Aplikasi Desktop) ZAP untuk menyediakan klien pengujian API yang kaya kepada pengguna.
Selain dokumentasi API, saya berencana menggunakan konverter swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) untuk menghasilkan dokumen API dalam format Markdown. Pendekatan ini (swagger-converter) menyederhanakan pembuatan dokumentasi RESTful API terbaru dengan menggabungkan dokumentasi yang ditulis tangan dengan dokumentasi API yang dibuat otomatis yang dihasilkan oleh Swagger. Hasilnya akan mirip dengan dokumentasi API GitHub. (https://developer.github.com/v3/). Dokumen tulisan tangan ini akan berisi dokumen tingkat tinggi yang menjelaskan cara penggunaan API untuk melakukan tugas tertentu. Misalnya, pemindaian Spider API adalah tugas yang berjalan lama dan pengguna harus terus memeriksa API untuk mengetahui status API. Oleh karena itu, dokumen tingkat tinggi ini akan membahas API mana yang akan digunakan untuk melakukan tindakan dan mengarah ke dokumen swagger yang dibuat secara otomatis untuk dibaca lebih lanjut.
Sebanyak lebih dari 380 API telah diterapkan di proxy ZA. Awalnya, saya mengusulkan untuk mendokumentasikan semua API dengan deskripsi API, informasi terkait parameter, respons keberhasilan dan kegagalan API. Contoh POC telah dilakukan, dan detail tambahan dapat dilihat dalam proposal tertaut.
Periode tiga bulan ini akan dibagi menjadi tiga fase. Fase pertama akan membuat spesifikasi Open API untuk Active Scan, Core API (150+). Sejalan dengan pembuatan file swagger, dokumentasi kasus penggunaan yang relevan/ dokumen tingkat tinggi tentang cara menggunakan API untuk melakukan tugas tertentu juga akan dibuat. File ini dapat diberi versi dan dibuat secara otomatis untuk menghilangkan pekerjaan manual, dan file markdown yang dihasilkan dapat dihosting sebagai halaman web atau diekspor sebagai PDF.
Fase kedua akan mencakup dokumentasi Spider, Autoupdate, Context, Status, Search API, dan pembuatan artikel kasus penggunaan yang relevan melalui file Markdown.
Fase terakhir akan mencakup API lainnya yang tidak terdokumentasi dan kasus penggunaannya yang relevan. Pada bulan lalu, saya juga berencana untuk membahas kasus penggunaan yang memerlukan pemanggilan beberapa komponen API untuk melakukan tugas.