NodeJS ve Swagger ile REST API Yazma
Merhabalar,
Bu yazıda son zamanların popüler Javascript frameworklerinden olan ve API yazımında da kullanılabilen NodeJS framework’ünde Swagger paketini kullanarak REST API tasarlayacağız. API tasarımına geçmeden önce Swagger’dan biraz bahsetmek istiyorum. API yazımlarında bir standart oluşturan Swagger API’ler için tasarım, geliştirme ve hızlıca test edebilme kolaylığı sağlamaktadır. Bu standart sayesinde birçok proje birbirine kolaylıkla entegre edebilir hale gelmektedir. YAML ve JSON formatlarıyla çalışan Swagger hakkında detalı bilgiye aşağıdaki linkten ulaşabilirsiniz.
Bu yazıda NodeJS ile birlikte Swagger’ın NPM paketini kullanacağız.
İlk olarak swagger paketini global paketlerimiz içerisine eklememiz gerekmektedir. Bu işlemi aşağıdaki komutu çalıştırarak kolayca yapabiliyoruz.
Swagger paketi kolayca yüklendikten sonra bize CLI servis hizmeti sağlamaktadır. Bu paketin kullanımı aşağıdaki gibidir.
Swagger CLI servisi sayesinde kolaylıkla template bir proje oluşturabilirsiniz.
Kullanmak istediğiniz framework’ü seçtikten sonra template proje başarılı bir şekilde oluşmaktadır.
Oluşan template projenin yapısı yukarıdaki gibidir. burada otomatik olarak iki script gelmektedir. İlk script server’ın ayağa kalmaksını sağlarken ikinci script yazılan unit testleri çalıştırmaktadır.
Swagger’ın default config bilgileri aşağıdaki gibi gelmektedir. Swagger ayarlarını bu config dosyasında dilediğiniz gibi yönetebilirsiniz.
Bu ayarları projenin ayağa kalkacağı bölüm olan app.js dosyasında entegre ettikten sonra proje hazır hale gelmektedir. Default olarak 10010 portundan ayağa kalkan bu projeyi istediğiniz uygun olan portlardan ayağa kaldırabilirsiniz.
Server’ı ayağa kaldırmak için start scriptini kullanacağız ve http://localhost:10010 portundan proje ayağa kalmış olacak.
Template projede http://localhost:10010/ route’u için tanım yapılmadığı için Error alacaktır.
Template projedeki örnek sorgu ise http://localhost:10010/hello?name=Muhtalip gibidir.
Server başarılı bir şekilde ayağa kalktıktan sonra artık Swagger ile birlikte controller tanımlarınızı yapabilir ve metotları entegre edebilirsiniz. Bu işlemi aşağıdaki komutu çalıştırarak yapacağız.
Komutu çalıştırdıktan sonra otomatık olarak Swagger Editorüne yönlendirileceksiniz. Swagger Editör sayesinde kolayca controller tanımlarınızı yapabilirsiniz. Swagger Editör YAML formatındaki bir dosyayla çalışmaktadır. YAML dosyasında değişiklik yaptıkca yandaki UI bileşeni de update olacaktır.
Burada bir controller oluşturduğumuzda temelde iki şey eklememiz gerekiyor. İlk olarak bir path tanımı yapmamız gerekiyor. Path tanımını yaparken metotun hangi Http protokülünü kullanacağını vermeniz gerekmektedir. x-swagger-router-controller alanı proje içerisinde metotun bulunduğu dosyayı işaret etmektedir. parameters tanım içinde parametre tanımlarınızı yapabilirsiniz. responses alanında ise döneceğiniz objeler bulunmaktadır. İkinci olarak da bu objeleri tanımladığımız definitions alanı. Burada dönecek olan objede alan zorunluluklarını ve tiplerini verebilirsiniz.
Swagger Editör üzerinden editlediğimiz YAML dosyası local projede de anlık olarak aynı şekilde update edilmektedir.
Swagger Editör’de oluşturmuş olduğunuz controller’ın arkasında çalışacak olan metotları controllers klasörünün altından oluşturabilirsiniz.
Servis yazılımında dokümantasyon ve standartlar oldukça önemlidir. Swagger ile birlikte servislerinizi standart bir şekilde yazabilir ve detaylı bir dökümantasyon oluşturabilirsiniz. Başka yazılarda görüşmek üzere…
Sağlıcakla,
Muhtalip Dede
