Merhaba,
Bir Web API geliştirdiğimizde, diğer geliştiricilerin API ile iletişim kurmaya çalışırken metotları sorgulayacakları parametreleri ve bu sorgular sonucunda alacakları geri dönüş bilgilerini bilmeleri gereklidir.
Örneğin, Backend tarafındasınız ve bir API geliştirmeniz istendi. Frontend ekibi de API ile iletişim kurup dönen verileri ara yüze yansıtacak.
Böyle bir durumda Frontend ekibine anlaşılır bir dokümantasyon sunmalısınız ki onlarda geliştirmelerini rahat bir şekilde yapabilsinler. Anlaşılır bir API dokümantasyonu ekipler arasındaki koordinasyonu sağlamak için büyük önem arz etmektedir.
Yazılımcı gözüyle bakacak olursak, kodlama kısmı bittiğinde yapılan geliştirmenin dokümantasyonunun hazırlanması genellikle geliştirmeden daha zor olmaktadır. Metotların, istek ve sonuç tiplerinin tek tek açıklanması vs vs… Bu probleme çözüm olarak Swagger hayat kurtarıcı olarak karşımıza çıkmaktadır.
Kısaca Swagger’ dan bahsetmek gerekirse;
Swagger, dinamik doküman oluşturma aracıdır. Oluşturduğumuz uç noktaları yakalayabilmek için tüm metotlarımızı tarar. GET, POST, PUT, DELETE ile işaretlenmiş olan metotları bir json dosyasında tutarak bunu dokümantasyon için kullanılan Swagger-UI arayüzüne gönderir.
Proje boyunca eklenen ya da değiştirilen metotlar dinamik olarak yakalanır ve güncellenir. Bu da biz geliştiricileri her seferinde doküman güncelleme maliyetinden kurtarır.
Aslında sadece Swagger kullanarak geliştirdiğiniz API‘ ın dokümantasyonunu kolay bir şekilde hazırlayabilirsiniz.
ReDoc entegrasyonu yapmadan önce swagger kullanmamış olanlar için daha önce yazmış olduğum Asp.Net Core WebApi Swagger Kullanımı yazısını okumalarını tavsiye ederim. Yazının ileriki kısmında Swagger entegre edilmiş bir API üzerinden ReDoc ekliyor olacağız
Şimdi gelelim ReDoc tarafına…
Madem Swagger ile otomatik olarak dokümantasyon hazırlanıyor o zaman neden ekstra olarak ReDoc kullanayım diye düşünüyor olabilirsiniz.
Bu durum kişiden kişiye göre değişebilir. Benim için tamamen daha kullanışlı ve şık bir görünüme sahip dokümantasyon sunmaktan ibaret.
Şunu da söylemek gerekirse, Swagger’ ın standart ara yüzünden memnun olmayanlar, Swagger’ da da özelleştirme yapılabiliyor. Ama ReDoc’ u ekledikten sonra bunu yapmaya çok fazla gerek olmadığını düşünenlerdenim.
Lafı daha fazla uzatmadan projemize ReDoc’ u entegre etmeye başlayabiliriz.
Projemizde Swagger paketlerinin eklenmiş olduğunu düşünerek sadece ReDoc için yapılacak işlemlerden bahsedeceğim.
Öncelikle projemize Swashbuckle.AspNetCore.ReDoc NuGet paketini ekliyoruz.
dotnet add package Swashbuckle.AspNetCore.ReDocDaha sonra Program.cs içerisinde uygulamanın ReDoc kullanacağını belirtip ayarlar kısmında bulunan SpecUrl alanına Swagger’ ın bize oluşturmuş olduğu json dosyasının yolunu yazıyoruz.
Sonrasında projemizde bulunan Properties dizini altındaki launchSettings.json dosyasından launchUrl özelliğini “api-docs” olarak güncelleyerek ReDoc’ u varsayılan başlangıç sayfası olarak ayarlıyoruz.
Evet…
Entegrasyon işlemi bu kadar.
Projemizi çalıştırdığımızda daha önce “/swagger/index.html” sayfası bizi karşılarken, launchSettings.json’ dan yaptığımız değişiklikten sonra açılış sayfamız “api-docs/index.html” olarak güncellenmiş oldu.
Bu arada yaptığımız işlem ReDoc’ un en sade haliyle entegre edilmiş hali.
İsteğe göre bazı ayarlar ile daha da özelleştirebilirsiniz.
Örneğin logo eklemek, stil dosyası ile özelleştirmek, bazı alanları gizlemek vs… Bu özellikleri deneyeceğim bir projeyi github hesabıma ekliyor olacağım.
Ücretli versiyonununda daha fazla özellik mevcut fakat ücretsiz versiyonunda da bazı özellikleri özelleştirmenize izin veriyor ReDoc eklentisi ve şu an bu benim için yeterli.
Sonuç olarak Swagger ve ReDoc;
API dokümantasyonu oluşturmak için ücretsiz, hızlı ve pratik bir çözümdür. Her ne kadar ReDoc’ un ücretli versiyonu olsa da ücretsiz versiyonu da dokümantasyonunuza güzel bir görüntü kazandırmaktadır.
Faydalı olması dileğiyle,
İyi çalışmalar…
