Bu yazı RESTFul Api Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız önce serinin diğer yazılarını okumanızı tavsiye ederim.

Dokümantasyon API’yi kodlamaktan çok daha zor bir süreç ve her ne kadar bunu otomatik yaptığını iddia eden yazılımlar varsa da, bu yazılımların bunu yapabilmesi için koda eklenmesi gereken açıklamalar -annotations- neredeyse bir doküman yazmak kadar zor. Amma abartmışsın, nesi bu kadar zor diyenler varsa iyi bir API dokümantasyonunun şu bilgileri içermesi gerektiğini hatırlatalım;

  • API uç noktaları (endpointler) neler?
  • Bu uç noktalar hangi operasyonları yapmak için kullanılıyor, hangi metotları destekliyor?
  • Bu uç noktaların beklediği parametreler ne? (Hangisi isteğe bağlı, hangisi mecburi?
  • Örnek istek içerik ve başlıkları
  • Örnek kodlar
  • Bu uç noktaların geri döndürebileceği değerler ne? Hangi format ve yapıda?
  • Örnek cevaplar
  • Olası hata kodları ve sebepleri ne?
  • Bu uç noktalara ulaşmak için bir kimlik doğrulama gerekiyor mu
  • Kimlik doğrulama gerektiren işlemler varsa bu nasıl yapılacak?
  • Rate limit var mı?
  • Lisans bilgileri, güvenlikle ilgili bilgiler, gizlilik bilgileri ve daha bir çok hikaye

Bütün bunları bir word dokümanı açıp eksiksiz yapabileceğinizi düşünüyorsanız ne ala, ama benim tecrübem ufak çaplı bir API’de bile bunun zorlayıcı olduğu.

Peki kolay dokümantasyon ve test için çözüm ne?

Sadede geleyim; Swagger platformu, Swagger (OpenAPI) spesifikasyonuna uygun API’ler tasarlamak, dokümante etmek, test etmek ve son olarak hata ayıklamak için kullanılabilecek bir çerçeve. Swagger bunun da ötesinde API’niz için otomatik istemci kütüphaneleri oluşturmak için de kullanılabiliyor. (Ben bu kısmını, yani CodeGen’i hiç tecrübe etmedim)

Swagger UI nedir?

Swagger UI, yani Swagger User Interface Swagger spesifikasyonuna uygun bir Api’yi görsel olarak tasarlamanızı sağlayan bir araç. Swagger platformundaki araçların veya swagger uyumlu bir sistemin sizden istediği şey OpenAPI spefikasyonuna uygun hazırlanmış bir JSON dosyası ile API tanımlarının verilmesi, işte Swagger UI bu dosyayı daha kolay hazırlamanızı, sonuçları görsel olarak görmenizi ve testlerinizi kolayca yapmanızı sağlıyor.

Şu adreste canlı bir swagger demosu var. Buraya girdiğinizde swagger UI ile görsel bir API tanımının nasıl yapıldığını görmüş olacaksınız.

Peki Swagger UI’yi nasıl kullanırım? Swagger Editor, UI ve Codegen araçları Swagger Hub üzerinden çevirim içi kullanmanız mümkün. Fakat swagger HUB yerel ağ ortamında geliştirme yaparken test işlevselliğini kaybediyor. Fakat Github’daki Swagger UI projesini klonlayıp, docker konteyneri olarak çalıştırmak gayet pratik. Bu şekilde kullanmanızı tavsiye ederim. Kullanım detaylarına burada girmiyor ve sizi Swagger dokümantasyonunu okumaya davet ediyorum. REST api tasarım inceliklerini araştıran ve bu yazıyı buraya kadar okuyan senin gibi değerli bir arkadaşın Swagger Editor UI’yi nasıl kullanacağının üstesinden de kendi geleceğini düşünüyorum. 🙂

Bir diğer alternatif PostMan

PostMan ücretli bir api tasarım, test ve dokümantasyon servisi. Bu ihtiyaçlar üzerinde takım olarak çevrimiçi bir platformada çalışmayı sağlıyor. Denemek isteyenler için tasarım ve test için temel anlamda kullanılabilecek ücretsiz bir çözümü de var. Bilgisayarınıza indireceğiniz PostMan istemcisi sayesinde yerel geliştirmeleriniz için de kullanabiliyorsunuz. Swagger’ı keşfedene kadar kullandığım bir servisti.

Advanced Rest Client – ARC

ARC sadece test işlevini bünyesinde barındıran, bilgisayarınıza yükleyerek çalıştırdığınız, basit ve kullanımı kolay bir REST istemcisi. Developer’a test imkanı sağlıyor ama işin tasarım, test ve dokümantasyon kısmı ile hiç bir ilgisi yok. Geliştricilern elinin altında bulunması gereken pratik bir araç.

Bu Yazıda Yapılan Değişiklikler
  • 11.05.2022: Yazı özeti düzenlendi.