İçindekiler
API projelerinde iyi bir dokümantasyon ve kolay test edilebilen mock sunucular üretmek, hem geliştirme hızını artırır hem de ekip içi iletişimi düzene sokar. Ücretsiz API dokümantasyon ve mock sunucu araçları arıyorsan, açık kaynak araçlar ve temel özellikleri ücretsiz sunan çözümler işini görebilir. Bu rehberde Swagger UI, Redoc, Mockoon, Prism ve Postman gibi popüler seçenekleri, hangi işlerde iyi olduklarını ve sınırlamalarını anlatıyorum.
Mevcut yazılarımızdan farklı olarak bu rehberde odak, sadece "dokümantasyon görüntüleme" değil; aynı zamanda yerel veya CI süreçlerine entegre edilebilen mock sunuculara da genişleyecek. Böylece hem API'yi belgeleyebilir hem de frontend ya da entegrasyon testleri için canlıymış gibi davranan sahte uç noktalar oluşturabilirsin.
Hızlı Karşılaştırma
| Program | Platform | En iyi olduğu iş | Ücret |
|---|---|---|---|
| Swagger UI | Web / Statik | OpenAPI tanımlarını interaktif gösterme | Ücretsiz |
| Redoc | Web / Statik | Okunabilir ve profesyonel API dokümantasyonu | Açık kaynak sürüm ücretsiz, ticari eklentiler ücretli |
| Mockoon | Windows, macOS, Linux | Lokal mock sunucular ve kolay senaryo oluşturma | Temel özellikler ücretsiz |
| Prism | CLI / Sunucu | OpenAPI'den gerçekçi mock ve şema doğrulama | Açık kaynak (temel ücretsiz) |
| Postman | Windows, macOS, Linux, Web | Koleksiyon temelli test ve mock sunucular | Ücretsiz planda sınırlamalar var |
Swagger UI: Hafif, standart uyumlu görüntüleyici
Swagger UI, OpenAPI (eski adıyla Swagger) tanımlarını alıp tarayıcıda interaktif bir şekilde gösteren, en yaygın kullanılan açık kaynak çözümlerden biridir. Bir HTML/JS bileşeni olarak kolayca projene eklenebilir veya statik dosya olarak barındırılabilir; pek çok framework ve CI hattı Swagger UI ile entegrasyon sağlar. Belgeyi okuyanların uç noktaları denemesine izin veren basit bir "Try it out" arayüzü sunar.
Teknik olarak çok hafiftir ve OpenAPI sözleşmesine sıkı sıkıya bağlı kalan projeler için ideal: endpoint listesi, parametreler, örnek istek/cevap gibi bölümleri okunaklı sunar. Ancak tasarım açısından daha fazla özelleştirme veya gelişmiş arama/kategorilendirme gerekiyorsa ek katmanlar veya stil değişiklikleri gerekebilir.
Artıları
- Doğrudan OpenAPI tanımlarını interaktif gösterir
- Kolay entegre edilir ve statik olarak barındırılabilir
- Açık kaynak ve geniş ekosisteme sahip
Eksileri
- Görsel olarak sınırlı, daha profesyonel dokümantasyon için ek çaba gerekebilir
- Mock veya gelişmiş senaryo desteği doğrudan yok
Kimler için? Basit, hızlı ve standart uyumlu bir API belge görüntüleyici isteyen geliştiriciler ve ekipler için.
Redoc: Okunabilir, profesyonel API belgeleri
Redoc, OpenAPI tanımlarını estetik ve okunaklı bir biçimde sunmak için tasarlanmış bir dokümantasyon renderer'ıdır. Özellikle büyük API yüzeyleri ve detaylı açıklamalar için daha net bir gezinme, içindekiler ve güzel tipografi sağlar. Redoc'un açık kaynak versiyonu, statik site olarak üretilebilen belgeler hazırlamak için yeterlidir; Redocly tarafında ise ticari eklentiler ve yönetim özellikleri bulunur.
Eğer hedefin kullanıcıların API'yi hızlı kavraması ve uzun dokümanlarda bile kaybolmamasıysa, Redoc iyi bir tercihtir. Ayrıca birçok statik site jeneratörü ve CI iş akışı ile birlikte çalışarak belgelerini otomatik olarak güncel tutabilirsin.
Artıları
- Uzun API dokümanlarında okunabilirliği yüksek
- Statik site oluşturma ve CI entegrasyonuna uygun
- Açık kaynak sürümüyle temel ihtiyaçları karşılar
Eksileri
- Tema ve görsel özelleştirme daha sınırlı olabilir, gelişmiş özellikler ücretli olabilir
Kimler için? Kurumsal görünümlü, okunması kolay ve bakım kolaylığı arayan ekipler için.
Mockoon: Lokal mock sunucular için hızlı çözüm
Mockoon, masaüstü uygulaması olarak çalışan ve hızlıca mock sunucular oluşturmanı sağlayan bir araçtır. GUI üzerinden endpoint'leri, yanıt şablonlarını, gecikme ve durum kodlarını tanımlayabilir, JSON şablonlarıyla dinamik cevaplar oluşturabilirsin. Lokal geliştirme veya demo amaçlı kullanımlar için kurulum sonrası birkaç tıklamayla çalışır hale gelir.
Mockoon özellikle frontend geliştiricilerinin backend hazır olmadan API ile çalışmasına olanak tanır. Ayrıca projeyi JSON dosyası olarak dışarı aktarabilirsin; bu sayede ekip içinde paylaşmak veya CI/CD pipeline'ına eklemek mümkün olur. Temel özellikleri ücretsizdir, ileri entegrasyonlar veya ekip özellikleri için farklı seçenekler olabilir.
Artıları
- GUI ile hızlı mock sunucu kurma
- Lokal geliştirme ve demo amaçlı çok pratik
- JSON şablonları ve gecikme gibi seçenekler sunuyor
Eksileri
- Büyük ölçekli entegrasyon veya paylaşılan bulut mock'ları için sınırlamalar olabilir
Kimler için? Hızlıca lokal mock sunucusu kurup frontend geliştirme veya demo ihtiyacı olan geliştiriciler için.
Prism: OpenAPI'den gerçekçi mock ve doğrulama
Prism, OpenAPI tanımlarını kullanarak istekleri taklit eden, yanıtları şemaya göre üreten ve gelen istekleri tanıma/doğrulama yapan bir CLI/sunucu aracıdır. Yani elindeki OpenAPI dosyasını canlıymış gibi davranan bir mock sunucuya dönüştürebilir ve aynı zamanda gelen isteklerin sözleşmeye uygunluğunu kontrol edebilir. Bu özellik test ve entegrasyon süreçleri için değerli bir katkı sağlar.
Sunucu modu, CI süreçlerinde veya test ortamlarında kontrollü davranış sergilemek için uygundur. Schema tabanlı olduğu için yanıtlarda rastgele veriler yerine tanıma uygun örnekler üretir; böylece tüketici taraf beklenen yapıyla daha gerçekçi test yapabilir.
Artıları
- OpenAPI'den tam otomatik mock üretir
- İstek doğrulama ile entegrasyon testlerine yardımcı olur
- CLI üzerinden CI'ye kolay eklenir
Eksileri
- Konfigürasyon ve gelişmiş davranışlar için öğrenme eğrisi olabilir
Kimler için? OpenAPI tabanlı, test odaklı mock'lar ve sözleşme doğrulaması isteyen ekipler için.
Postman: Koleksiyon tabanlı test ve temel mock desteği
Postman, API geliştirme ve test süreçlerinde çok yaygın bir araçtır. Koleksiyonlar aracılığıyla istekleri organize edebilir, otomasyon testleri yazabilir ve aynı zamanda Postman platformunda mock sunucular oluşturabilirsin. Mock özellikleri hızlı prototipleme ve paylaşılan demo için kullanışlıdır; ayrıca Postman'ın rich UI'si ekip paylaşımı ve dokümantasyon oluşturma açısından avantaj sağlar.
Ancak Postman'ın ücretsiz planında çalışma alanı ve paylaşılan mock/ci entegrasyonları gibi özelliklerde sınırlamalar olabilir. Yine de tek başına hem dokümantasyon hem de temel mock gereksinimlerini bir arada yönetmek isteyen küçük ekipler için pratik bir çözüm sunar.
Artıları
- Test, koleksiyon ve mock'ı tek platformda toplar
- Ekip paylaşımı ve dökümantasyon özellikleri güçlü
- Yeni başlayanlar için öğrenmesi kolay arayüz
Eksileri
- Ücretsiz planda sınırlamalar var; büyük ekip ve ağır kullanım için ücretli plana ihtiyaç doğabilir
Kimler için? Test otomasyonu ve ekip içi paylaşım ile birlikte temel mock ihtiyaçları olan küçük ekipler ve freelance geliştiriciler için.
Hangisini Seçmelisin?
- Basit ve standart uyumlu dokümantasyon istiyorsan: Swagger UI
- Profesyonel, okunabilir ve statik site odaklı belgeler için: Redoc
- Lokal hızlı mock sunucusu kurmak istiyorsan: Mockoon
- OpenAPI tabanlı gerçekçi mock ve sözleşme doğrulaması gerekiyorsa: Prism
- Test, koleksiyon ve paylaşımı tek araçta toplamak istiyorsan: Postman
Sıkça Sorulan Sorular
Swagger UI ile Redoc arasındaki temel fark nedir?
İkisi de OpenAPI tanımlarını gösterir; Swagger UI daha minimal ve "Try it out" gibi etkileşim odaklıyken, Redoc uzun ve kapsamlı belgeleri daha okunaklı sunacak şekilde tasarlanmıştır. Seçim, daha çok okunabilirlik mi yoksa etkileşim mi istediğine bağlıdır.
Mockoon bir ekip için yeterli mi?
Mockoon lokal geliştirmeler ve küçük ekipler için çok pratiktir; GUI sayesinde hızlıca mock'lar oluşturursun. Ancak paylaşılan, yüksek erişimli bulut mock'ları veya gelişmiş erişim kontrolü gerekiyorsa ek çözümler veya servisler gerekebilir.
OpenAPI spesifikasyonu kullanmak zorunlu mu?
Zorunlu değil ama OpenAPI kullanmak standart bir sözleşme sağlar; hem dokümantasyon araçları hem de Prism gibi mock çözümleri OpenAPI ile daha iyi çalışır. Eğer zaten başka bir belge formatın varsa, araç destekleri doğrultusunda dönüştürme gerekebilir.
Dokümantasyonu güncel tutmanın pratik yolu nedir?
Dokümanları CI/CD hattına entegre ederek her deploy veya sürümde OpenAPI dosyasını otomatik olarak üretebilir ve statik site üreterek (ör. Redoc veya Swagger UI ile) yayınlayabilirsin. Bu, manuel güncelleme ihtiyacını azaltır ve dokümanın kodla senkron kalmasını sağlar.
Hangi araç daha az öğrenme eğrisi sunuyor?
Postman ve Mockoon, grafiksel arayüzleri sayesinde yeni başlayanlara daha yakın ve hızlı adapte olunur. Prism ve Swagger UI daha çok OpenAPI bilgisi gerektirebilir, fakat sundukları otomasyon ve entegrasyon avantajı genellikle buna değer.
