Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- OWASP Foundation
- Teknik yazar:
- sshniro
- Proje adı:
- ZAP API Dokümanlarında Geliştirme
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
ZAP, mümkün olan hemen hemen her şeyi masaüstü arayüzü üzerinden gerçekleştirmemizi sağlayan son derece güçlü bir API'ye sahip. Ancak API'leri etkili bir şekilde kullanmak için kullanıcı arayüzünü iyi anlamak gerekir. Bunun nedeni, API'lerin çoğunun ZA proxy'sinin kullanıcı arayüzüyle doğrudan ilişkili olmasıdır. İyi belgelenmiş bir API ve kullanım/ kullanım alanı dokümanı, API'leri denemeye çalışırken bu darboğazdan kurtulmanıza yardımcı olabilir.
Şu anda API dokümanları otomatik olarak oluşturuluyor, ilgili parametrelerle ilgili çok az bilgi veriyor ve topluluğun API dokümanlarına katkıda bulunması için daha az fırsat sunuyor. Ayrıca, ZAP'ın içinde kullanılan web tabanlı kullanıcı arayüzü (masaüstü sürümü) de çağrı için otomatik olarak oluşturulmuş API listesini kullanır. Bu web tabanlı API çağırma kullanıcı arayüzü, API'nin nasıl kullanılacağı ve API'ler çağırıldığında ne bekleneceği ( ör. API sonuçları) hakkında da çok sınırlı bilgi sağlar. Bu nedenle bu teklifte, API'leri belgelemek için yeni bir yaklaşım öneriyorum.
Amacımız, API dokümanlarını Open API 3 Specifications ile yeniden oluşturmaktır. OpenAPI, geliştiricilerin, test kullanıcılarının ve geliştirme ekiplerinin API'leri oluşturması, sürdürmesi ve test etmesi için ortak bir çerçeve sağlar. ZAP için doldurulmuş OpenAPI spesifikasyonları, swagger dosyalarını otomatik olarak oluşturmak için kullanılabilir. Swagger dosyaları, kullanıcılara zengin bir API test istemcisi sağlamak için ZAP'ın web uygulaması (masaüstü uygulaması) kullanıcı arayüzüne entegre edilebilir.
API dokümanları dışında, API dokümanlarını Markdown biçiminde oluşturmak için swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) dönüştürücüsünü kullanmayı planlıyorum. Bu yaklaşım (swagger-converter), elle yazılmış dokümanları Swagger tarafından üretilen otomatik olarak oluşturulmuş API dokümanlarıyla birleştirerek güncel RESTful API dokümanlarının oluşturulmasını basitleştirir. Sonuçlar, Github'ın API belgelerine benzer. (https://developer.github.com/v3/). Bu el yazısı dokümanında, belirli bir görevi gerçekleştirmek için API'lerin nasıl kullanılması gerektiğini açıklayan üst düzey belgeler bulunur. Örneğin, Spider API taraması uzun süren bir işlemdir ve kullanıcı, API'nin durumunu öğrenmek için API'yi sürekli olarak sorgulaması gerekir. Bu nedenle, bu üst düzey belgelerde bir işlem gerçekleştirmek için hangi API'lerin kullanılacağı açıklanır ve daha fazla okuma için otomatik olarak oluşturulmuş swagger belgelerine yönlendirilir.
ZA proxy'de toplam 380'den fazla API uygulanmıştır. İlk olarak, tüm API'leri API'lerin açıklaması, parametreleri, başarı ve başarısızlık yanıtları ile birlikte belgelemeyi öneriyorum. Halihazırda bir örnek POC yapıldı ve ek ayrıntılar bağlantı verilen teklifte görülebilir.
Üç aylık süre üç aşamaya ayrılır. İlk aşamada, Active Scan, Core API'ler (150+) için Open API spesifikasyonları oluşturulacak. Swagger dosyalarını oluşturmaya paralel olarak, ilgili kullanım alanı dokümanları/ belirli görevleri gerçekleştirmek için API'lerin nasıl kullanılacağına dair üst düzey belgeler de oluşturulacaktır. Bu, manuel çalışmaları kaldırmak için sürüm belirlenebilir ve otomatik olarak oluşturulabilir ve sonuç Markdown dosyaları web sayfası olarak barındırılabilir veya PDF olarak dışa aktarılabilir.
İkinci aşama ise Örümcek, Otomatik Güncelleme, Bağlam, Durum, Arama API'lerinin belgelenmesini ve Markdown dosyalarıyla ilgili kullanım alanı makalelerinin oluşturulmasını kapsar.
Son aşamada, dokümanları olmayan API'lerin geri kalanı ve ilgili kullanım alanları ele alınacaktır. Son 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.