Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- Yayasan OWASP
- Penulis teknis:
- sshniro
- Nama proyek:
- Penyempurnaan Dokumentasi API ZAP
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
ZAP memiliki API yang sangat canggih yang memungkinkan kami melakukan hampir semua hal yang memungkinkan melalui antarmuka desktop. Namun, untuk menggunakan API secara efektif, diperlukan pemahaman yang baik tentang UI. Hal ini karena sebagian besar API berkorelasi langsung dengan antarmuka pengguna proxy ZA. API yang terdokumentasi dengan baik dan dokumen kasus penggunaan/ penggunaan dapat membantu mengatasi bottleneck ini saat mencoba API.
Saat ini, dokumen API dibuat secara otomatis, memberikan sedikit informasi mengenai parameter yang dilibatkan, dan memberikan lebih sedikit kesempatan bagi komunitas untuk berkontribusi pada dokumentasi API. Selain itu, UI berbasis web (versi desktop) yang digunakan dalam ZAP juga menggunakan daftar API yang dibuat otomatis untuk pemanggilan. UI pemanggilan API berbasis web ini juga memberikan informasi yang sangat terbatas tentang cara menggunakan API dan hal yang diharapkan saat memanggil API ( hasil Eg- 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 developer untuk membangun, memelihara, dan menguji API. Spesifikasi Open API yang lengkap untuk ZAP dapat digunakan untuk membuat file swagger secara otomatis. File Swagger dapat diintegrasikan ke UI aplikasi web (Aplikasi Desktop) ZAP untuk menyediakan klien pengujian API lengkap kepada pengguna.
Selain dokumentasi API, saya berencana menggunakan pengonversi 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 secara manual dengan dokumentasi API yang dibuat secara otomatis yang diproduksi oleh Swagger. Hasilnya akan serupa dengan dokumentasi API GitHub. (https://developer.github.com/v3/). Dokumen tulisan tangan ini akan berisi dokumen tingkat tinggi yang menjelaskan bagaimana API harus digunakan 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 380+ API telah diimplementasikan di proxy ZA. Awalnya saya mengusulkan untuk mendokumentasikan semua API dengan deskripsi untuk API, informasi mengenai parameter, respons keberhasilan, dan kegagalan API. Contoh POC sudah dilakukan, dan detail tambahan dapat dilihat dalam proposal yang ditautkan.
Periode tiga bulan ini akan dibagi menjadi tiga fase. Fase pertama akan membuat spesifikasi Open API untuk Pemindaian Aktif, API Inti (150+). Bersamaan dengan pembuatan file swagger, dokumentasi kasus penggunaan yang relevan/ dokumen tingkat tinggi tentang cara menggunakan API untuk melakukan tugas tertentu juga akan dibuat. Halaman ini dapat dibuat versi dan dibuat secara otomatis untuk menghapus tugas manual dan file markdown yang dihasilkan dapat dihosting sebagai halaman web atau diekspor sebagai PDF.
Fase kedua akan membahas dokumentasi Spider, Autoupdate, Context, Status, Search API, dan membuat artikel kasus penggunaan yang relevan melalui file Markdown.
Fase terakhir akan membahas API lainnya yang tidak terdokumentasi dan kasus penggunaannya yang relevan. Pada bulan lalu, saya juga berencana membahas kasus penggunaan yang memerlukan pemanggilan beberapa komponen API untuk melakukan tugas.