İlk başta Swagger’ı size tanıtarak başlamak istiyorum. Swagger size Api dokümantasyonu oluşturabileceğiniz bir arayüz sunmaktadır. Sunucunuz aracılığıyla Api yapınızın nasıl çalıştığını geliştiricilerinize veya kullanmak isteyen firmalara açabilirsiniz. Bu sayede geliştiriciler veya firmalar sizin API’leriniz üzerinde farklı uygulamalar geliştirebilirler ya da sizin yazılımınızı kendi yazılımlarına entegre edebilirler.
Swagger yukarda görüldüğü üzere HTTP API’ler eklemenize olanak sunar. API’ler private (özel) ve public (genel) ikiye ayrılır. Bu sebeple HTTP API’ler Swagger üzerinde Swagger 2.0.0 ve Open API 3.0 olarak oluşturulabilir. Public yani herkese açık API’ler Open Api ile oluşturulurken private yani özel API’ler Swagger ile oluşturulur.
Swagger üzerinde farklı HTTP methodlarına karşılık gelen farklı işlem tipleri barındırılabilir ve gruplandırılabilir. Swagger içerisinde yine örnek header, body, query ve url parametreleri farklı isteklerde tanımlanabilir. Swagger HTTP cevapları için örnek veri modelleri ve cevap yapıları tanımlamanıza da izin verir. Bu sayede istek üzerinde giden ve gelen parametre ve verilere ulaşabilirsiniz.
Swagger’ın bir diğer özelliği de örnek AUTH yani yetkilendirme parametrelerinin tanımlanabilmesidir. Bunun için Swagger üzerinde bir güvenlik mekanizması bulunur ve farklı tokenler burada barındırılabilir.
Swagger tanımlanan istekler üzerinden HTTP örnek istekler oluşturmanızı da sağlar. Yani tanımlanmış bir istek vasıtasıyla sistemdeki yapıları kontrol edebilir ve istek yollayabiliriniz. Bu özellik sayesinde herhangi başka bir araç olmadan dokümantasyon, test ve geliştirme aşamalarınızı otomatikleştirebilirsiniz.
express-swagger-producer:
Express Swagger Producer Doctrine-File ve express-swaggerize-ui kullanarak kod üzerinde yorum satırları aracılığıyla Swagger oluşturmanızı sağlar. Express Swagger Producer vasıtasıyla cevap modellerini tek bir yere toplayabilirsiniz. Bu sayede aynı cevap yapısını birden fazla istek için tekrar tekrar kullanabilirsiniz. Express Swagger Producer TypeScript environment’ını destekler.
Modüle ve daha fazla bilgiye bu linkten ulaşabilirsiniz
https://www.npmjs.com/package/express-swagger-producer
Bu komutu kullanarak Express Swagger Producer modülünü kodunuza dahil edebilirsiniz.
Express Swagger Producer modülünü kullanabilmek için express üzerinde tanımlamasını bu şekilde gerçekleştirebilirsiniz. Bu tanımlamayı gerçekleştirdikten sonra express-swagger-producer modülü çalışmaya başlayacaktır. Buradaki opsiyon tanımlamasına göre
http://localhost/api-docs linki aracılığıyla Swagger’a ulaşabilirsiniz. Buradaki swagger üretmek için kullanılan json dosyasına da http://localhost/api-docs.json linkinden ulaşabilirsiniz. Yukardaki ayarlarda kendi uygulamanıza göre yanında bulunan yorumlar üzerinden tanımlamalar gerçekleştirebilirsiniz.
Cevap modeli tanımlayabilmek için bu kodu kullanabiliriz.
Buradaki Product modeli altında Point array’i modeli tanımlanabilir. Bu sayede bir yapı diğer yapı içerisine girebilir. @typedef vasıtasıyla model ismi eklenir. @property aracılığıyla da istek sonucu kısmında dönülecek veriler tanımlanabilir.
Bu kodu kullanarak istek cevabı modelimizin isminin Product olduğunu tanımlamış oluyoruz.
Bu kodu kullanarak y parametresinin integer olduğunu, istek içerisinde zorunlu olduğunu, açıklamasının ‘Some description for point’ olduğunu ve örnek değerinin de ‘1234’ olduğunu anlıyoruz.
Bir route veya istek tanımlaması yapabilmek için yukarıdaki kodu kullanabiliyoruz.
Bu kısımda isteğin açıklamasını yapabiliyoruz. Alt alta açıklamalar ekleyebiliriz ve farklı bilgiler tanımlayabiliriz.
Bu kısım isteğin route bilgisini ve HTTP methodunu tanımlamamızı sağlar
Bu kısımda istek içerisinde göndermek istediğimiz parametrelerin tipini, modelini, HTTP parametresi tipini, zorunlu olup olmamasını, açıklamasını ve örnek verisini girebiliriz. Bu koddan birden fazla kere yazabilir ve bütün parametrelerimizi alt alta sıralayabiliriz
Bu alanda istekleri gruplayabiliriz ve aynı modele bakan istekleri aynı yerde toplayabiliriz.
Bu kısımda operationId tanımlayabilir ve ardı ardına kullanılan istekleri aynı operationId altına toplayabiliriz. Bu sayede birbiri ardına gönderilmesi gereken istekleri tek bir yerden açıp kapatabiliriz. Özellikle karmaşık sistemlerde bu özellik çok faydalı olmaktadır.
Bu kısımlarda gönderilebilecek ve alınabilecek veri yapılarını tanımlayabiliriz. Bu sayede geliştiricilere yol gösterebiliriz. İlk kısım isteğin application/json ve application/xml veri tipini cevap olarak dönebildiğini söylemektedir. İkinci kısım isteğin application/json ve application/xml veri tipini işleyebildiğini söylemektedir.
Bu kısımda isteğin bir cevap modeli veya verisi döndüğünü tanımlamaktayız. Basitçe bu kısımda Product modelini 200 durum kodu ile döndüğünü anlamaktayız.
Bu kısımda header ve limitler tanımlanabilir. Kısaca bu bölümde saatte 300 adet isteğin kullanıcı tarafından gönderilebileceği tanımlanmaktadır.
Bu bölümde isteğin güvenlik modeli ve güvenlik yapısı tanımlanmaktadır.
Yazımı okuduğunuz için teşekkür ederim.
https://www.cangokceaslan.com/courses
linkine tıklayarak eğitimlerime ulaşabilirsiniz.