Swagger ile Restful API Dökümanı Oluşturma | Sezer Bozkır | Sezer Bozkır
Restful API oluştururken, kod mimarisini ve işlevlerini açıklamakta kullanılan swagger harika bir arayüze ve kaliteli dokümana sahip güzel bir araç.
Şu bir gerçek ki geliştiricilerin sıkıntılarından birisi de yazılan kodu doküman haline getirmektir. İşte bu iş için adamlar düşünmüş “bir sistem oluşturalım, geliştirici isterse önce dokümanı yazsın, oradan aldığı iskeleti IDE’ye aktarıp oradan dokümana uygun yapının gövdesini yazsın, isterse de doctstring’ler üzerinden şemayı biz oluşturalım” demişler ve Swagger’ı çıkartmışlar.
Swagger entegrasyonu için buradan kullanılabilecek kütüphanelere ulaşabilirsiniz;
Bu konuda 2 yöntem mevcut,
Swagger online editör vasıtasıyla mimariyi oluşturup, JSON ya da YAML biçiminde almak.
Swaggerhub üzerinden mimariyi oluşturmak ya da Hub’daki mimarilerden bir tanesini seçip direk kullanmak.
Örnek bir kullanımla açıklamak daha iyi olacak, swagger editörü açtığınız zaman size şablonlar sunulmakta, ister bu şablonları kullanabilirsiniz, isterseniz de online editörde hali hazırda varolan şablonu özelleştirerek kullanabilirsiniz. Ben online editör üzerinden ilerleyeceğim. Online editörün sayfasına giriyoruz;
Karşımıza hazır şablon sunulmuş oluyor, ilk kısımda projenin tanımı ve içeriğine dair bilgi kısmı bulunuyor, sol tarafta yazdığınız şemanın sağda gösterimi interaktif şekilde sunulmakta, hatalı yazdığınızda ise hata mesajları verilmekte.
Buradan sonraki kısımda, “paths” kısmında API’nin hangi path’lerden nasıl tetikleneceğini açıklamaya başlıyorsunuz. Editörde varsayılan olarak “/pet” geldiğinde nasıl tepki vereceğii açıklanmış durumda.
Swagger kullanımıyla alakalı dökümana buradan ulaşabilirsiniz;