Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- OWASP Vakfı
- Teknik yazar:
- sshniro
- Projenin adı:
- ZAP API Belgelerinde İyileştirmeler
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
ZAP, masaüstü arayüzü üzerinden mümkün olan hemen hemen her şeyi yapmamıza olanak tanıyan son derece güçlü bir API'ya sahip. Ancak API'leri etkili şekilde kullanmak için kullanıcı arayüzünün iyi anlaşılması gerekir. Bunun nedeni, çoğu API'nin ZA proxy'sinin kullanıcı arayüzüyle doğrudan ilişkili olmasıdır. İyi hazırlanmış bir API ve kullanım/ kullanım alanı belgesi, API'leri denerken bu sorunun üstesinden gelmenize yardımcı olabilir.
Şu anda API belgeleri otomatik olarak oluşturulmakta, ilgili parametreler hakkında çok az bilgi sağlamaktadır ve topluluğun API belgelerine katkıda bulunması için daha az fırsat sunmaktadır. Ek olarak, ZAP içinde kullanılan web tabanlı kullanıcı arayüzü (masaüstü sürümü), çağrı için otomatik olarak oluşturulan API listesini de kullanır. Bu web tabanlı API çağrı kullanıcı arayüzü, API'nin nasıl kullanılacağı ve API'leri çağırırken neler bekleneceği ( ör. API sonuçları) hakkında da çok sınırlı bilgi sağlar. Bu nedenle bu teklifte, API'ları belgelemek için yeni bir yaklaşım öneriyorum.
Amaç, API belgelerini Open API 3 Specifications ile yeniden oluşturmaktır. Open API; geliştiriciler, test kullanıcıları ve geliştirici operasyonları için API'leri derlemeleri, sürdürmeleri ve test etmeleri amacıyla ortak bir çerçeve sağlar. ZAP için tamamlanan Open API özellikleri, promosyon dosyalarının otomatik olarak oluşturulması için kullanılabilir. Swagger dosyaları, kullanıcılara zengin bir API test istemcisi sağlamak için ZAP'nin web uygulaması (Masaüstü Uygulaması) kullanıcı arayüzüne entegre edilebilir.
API dokümanlarını Markdown biçiminde oluşturmak için API belgelerinin yanı sıra swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) dönüştürücüsünü kullanmayı planlıyorum. Bu yaklaşım (swagger-converter), elle yazılmış belgeleri Swagger tarafından otomatik olarak oluşturulan API belgeleriyle birleştirerek güncel RESTful API belgelerinin oluşturulmasını basitleştirir. Sonuçlar GitHub'un API dokümanlarına benzer olacaktır. (https://developer.github.com/v3/). Bu el yazısıyla yazılmış doküman, belirli bir görevi gerçekleştirmek için API'lerin nasıl kullanılması gerektiğini açıklayan üst düzey dokümanlar içerir. Örneğin, Örümcek API taraması uzun süren bir görevdir ve kullanıcının, API'nin durumunu öğrenmek için API'yi sürekli olarak yoklaması gerekir. Dolayısıyla bu üst düzey belgelerde, bir işlemi gerçekleştirmek için hangi API'lerin kullanılacağı açıklanır ve daha sonra okunması için otomatik olarak oluşturulmuş promosyon dokümanlarına işaret edilir.
ZA proxy'sinde toplam 380'den fazla API uygulanmıştır. Başlangıçta API'lerin açıklamasıyla, API'lerin parametreleriyle, başarı ve hata yanıtlarıyla ilgili bilgilerle tüm API'ları belgelemeyi teklif ediyorum. Daha önce örnek bir POC hazırlandı ve ek ayrıntılar bağlı teklifte görülebilir.
Üç aylık dönem üç aşamaya ayrılacaktır. İlk aşamada, Aktif Tarama ve Temel API'ler (150'den fazla) için Open API özellikleri oluşturulacaktır. Promosyon dosyalarının oluşturulmasıyla birlikte, alakalı kullanım alanı belgeleri/ API'lerin belirli görevleri gerçekleştirmek için nasıl kullanılacağına dair üst düzey dokümanlar da oluşturulacaktır. Manuel çalışmaları kaldırmak için bu dosya sürümü oluşturulabilir ve otomatik olarak oluşturulabilir. Sonuç olarak, yapılan Markdown dosyaları web sayfası olarak barındırılabilir veya PDF olarak dışa aktarılabilir.
İkinci aşamada Örümcek, Otomatik Güncelleme, Bağlam, Durum, Arama API'lerinin belgelenmesi ve Markdown dosyalarıyla alakalı kullanım alanı makalelerinin oluşturulması ele alınacak.
Son aşamada, diğer belgelenmemiş API'ler ve bunların ilgili kullanım alanları ele alınacaktır. Geçen ay, bir görevi gerçekleştirmek için birden fazla API bileşeninin çağrılmasını gerektiren kullanım alanlarını da ele almayı planlıyorum.