Apidog CLI ve Specmatic Karşılaştırması

API'leri önce bir spesifikasyondan oluşturuyorsanız, pratik karar şudur: OpenAPI dosyanızı yürütülebilir sözleşme kontrollerine dönüştüren bir araç mı kullanacaksınız, yoksa API'yi tasarlama, mocklama, test etme ve CI'da çalıştırma akışını tek yerde mi yöneteceksiniz? Specmatic ve Apidog CLI ikisi de “önce spesifikasyon” yaklaşımını destekler; ancak farklı problemleri çözer. Bu yazıda Specmatic ile Apidog CLI'ı gerçek API sözleşme testi pratikleri ve resmi OpenAPI Spesifikasyonu bağlamında karşılaştıracağız.

Apidog'u bugün deneyin

Kısa versiyon

Specmatic, API spesifikasyonunuzu yürütülebilir bir sözleşme gibi ele alır. OpenAPI veya desteklenen başka bir spesifikasyondan testler üretir, çalışan sağlayıcı servisi bu sözleşmeye göre doğrular ve aynı sözleşmeden tüketiciler için stub/mock servis sağlayabilir. Mikroservislerde tüketici/sağlayıcı sözleşme doğrulaması ana probleminizse güçlü bir seçenektir.

Apidog ise önce spesifikasyon mantığıyla çalışan daha geniş bir API platformudur. API'yi OpenAPI'ye göre görsel olarak tasarlar, schema tabanlı mock servis oluşturur, işlevsel test senaryoları yazar ve bunları CI'da apidog run ile çalıştırırsınız. REST, GraphQL, gRPC, WebSocket ve daha fazlasını aynı iş akışında yönetebilir.

Özet karar:

• Specmatic: Sözleşme doğrulaması, provider verification, stub olarak sözleşme.
• Apidog CLI: Tasarım, mock, işlevsel test, CI çalıştırması.
• Birlikte kullanım: OpenAPI ortak doğruluk kaynağıysa ve hem yaşam döngüsü yönetimi hem de sıkı sözleşme kapısı istiyorsanız mantıklı olabilir.

Specmatic neyi iyi yapar?

Specmatic'in temel yaklaşımı nettir: spesifikasyon sözleşmedir ve bu sözleşme çalıştırılabilir olmalıdır.

Bir OpenAPI, AsyncAPI, GraphQL, gRPC veya WSDL dosyası verirsiniz; Specmatic bu dosyadan pozitif ve negatif test senaryoları türetir. Böylece her sözleşme kontrolünü elle yazmanız gerekmez.

Tipik kullanım akışı:

# Örnek akış
# 1. API spesifikasyonunu repo içinde tutun
# 2. Servisi ayağa kaldırın
# 3. Specmatic ile sağlayıcıyı spesifikasyona karşı doğrulayın

Specmatic'in öne çıkan iki kullanım alanı vardır.

1. Sağlayıcı doğrulaması

Specmatic, çalışan servisinizi spesifikasyona göre test eder.

Örneğin OpenAPI dosyanız şu yanıtı vaat ediyorsa:

paths:
  /users/{id}:
    get:
      responses:
        "200":
          description: User detail
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - email
                properties:
                  id:
                    type: string
                  email:
                    type: string

Ama uygulama email alanını döndürmüyorsa, sözleşme testi bunu yakalar. Bu, özellikle farklı ekiplerin sahip olduğu servislerde kırılmaları erken görmek için değerlidir.

2. Sözleşmeden stub/mock servis

Aynı spesifikasyon, tüketici ekiplerin geliştirme sırasında kullanabileceği bir stub servis olarak da çalışabilir.

Pratik etkisi:

• Frontend veya başka bir tüketici ekip gerçek backend'i beklemez.
• Stub servis OpenAPI sözleşmesinden türediği için davranış ortak kaynağa bağlı kalır.
• Sağlayıcı ve tüketici ekipler aynı sözleşme üzerinden hizalanır.

Specmatic; GitHub'da açık kaynak çekirdeğe, CI/CD için CLI kullanımına ve ticari Studio/Insights katmanlarına sahiptir. OpenAPI dışında AsyncAPI, GraphQL, gRPC, WSDL ve Kafka, JMS, RabbitMQ gibi olay güdümlü arka uçları da destekler.

Specmatic'i özellikle şu durumda düşünün:

“Servislerimiz bağımsız dağıtılıyor ve ekipler arası sözleşme kırılmaları production'a yaklaşmadan yakalanmalı.”

Dikkat edilmesi gereken nokta: Specmatic bir API tasarım platformu veya tam kapsamlı işlevsel test yönetim aracı olmaya çalışmaz. Spesifikasyonu başka bir yerde yazar ve sürdürürsünüz; Specmatic bu spesifikasyonun uygulanıp uygulanmadığını doğrular.

Apidog CLI neyi iyi yapar?

Apidog CLI, Apidog platformunda oluşturduğunuz API testlerini komut satırından çalıştırmak için kullanılır. API'yi Apidog içinde tasarlar, mock servis oluşturur, test senaryolarını hazırlar ve pipeline içinde apidog run ile başsız şekilde çalıştırırsınız.

Kurulum, bayraklar ve çıkış kodları için apidog run komut referansına bakabilirsiniz.

Tipik CI akışı şöyle görünür:

# Apidog CLI ile testleri çalıştırma
apidog run

Pipeline mantığı:

# Örnek GitHub Actions iskeleti
name: API tests

on:
  push:
    branches:
      - main

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog tests
        run: apidog run

Not: Gerçek komut bayrakları, token ve proje yapılandırması kullandığınız Apidog kurulumuna göre değişir. Ayrıntılar için CLI dokümantasyonunu kullanın.

Apidog'un farklılaştığı yerler şunlardır.

1. Tasarım, mock ve test aynı iş akışında

Apidog'da OpenAPI tanımını görsel olarak oluşturur veya içe aktarırsınız. Ardından:

1. Endpoint'leri ve şemaları tanımlarsınız.
2. Bu şemadan mock yanıtlar üretirsiniz.
3. Aynı API tanımına karşı test senaryoları yazarsınız.
4. Senaryoları CI'da çalıştırırsınız.

Bu yaklaşım, tasarım ile doğrulama arasındaki kopukluğu azaltır. Detaylı örnek için şema öncelikli mock iş akışı kılavuzuna bakabilirsiniz.

2. Sadece schema kontrolü değil, işlevsel test akışları

Apidog'da testler yalnızca “yanıt şemaya uyuyor mu?” kontrolünden ibaret değildir. Senaryo içinde:

• İstekleri zincirleyebilirsiniz.
• Bir adımdan dönen veriyi sonraki adıma aktarabilirsiniz.
• Yanıt değerleri için assertion yazabilirsiniz.
• Veri odaklı test çalıştırabilirsiniz.

Örnek senaryo mantığı:

1. POST /auth/login
   - token değerini yanıttan al

2. GET /users/me
   - Authorization header içinde token kullan
   - status code 200 olmalı
   - response.email boş olmamalı

3. PATCH /users/me
   - kullanıcı bilgisini güncelle
   - güncellenen alan beklenen değerle dönmeli

Bu, saf sözleşme testinden çok uçtan uca API testine yakındır.

3. Çok protokollü test kapsamı

Apidog; REST, GraphQL, gRPC, SOAP ve WebSocket gibi farklı API türlerini aynı platformda yönetebilir. Eğer sisteminiz yalnızca REST'ten oluşmuyorsa, test ve dokümantasyon iş akışını tek yerde tutmak pratik olabilir.

4. CI için apidog run

apidog run, Apidog'daki görsel test senaryolarını pipeline içinde çalıştırmanızı sağlar. CLI çalıştırması:

• Başsız çalışır.
• Standart çıkış kodları döndürür.
• CI/CD araçlarına entegre edilebilir.
• Raporlama çıktılarıyla otomasyon akışına bağlanabilir.

Daha kapsamlı bir kurulum için Apidog CLI tam kılavuzuna bakabilirsiniz.

Dikkat edilmesi gereken nokta: Apidog, yanıtları OpenAPI şemanıza göre doğrular ve işlevsel testleri CI'da çalıştırır. Ancak Pact tarzı tüketici odaklı sözleşme aracısı değildir. Amacınız bağımsız tüketici ve sağlayıcı repoları arasında resmi bir sözleşme el sıkışması kurmaksa, Specmatic bu alana daha doğrudan odaklanır.

Yan yana karşılaştırma

Alan	Specmatic	Apidog CLI
Birincil vurgu	Kod olarak sözleşme: sağlayıcıyı spesifikasyona karşı doğrulama, sözleşmeden stub	Önce spesifikasyon tasarımı, mock, işlevsel test, CI çalıştırması
Test üretimi	Spesifikasyondan pozitif/negatif testleri otomatik üretir	Senaryoları görsel olarak oluşturursunuz; schema doğrulaması yerleşiktir
Sağlayıcı/tüketici sözleşme doğrulaması	Temel güç alanı	Schema doğrulaması yapar; sözleşme aracısı değildir
Mocking	Sözleşmeden hizmet sanallaştırması	OpenAPI tasarımından schema odaklı mock sunucu
Protokoller	OpenAPI, AsyncAPI, GraphQL, gRPC, WSDL, Kafka, JMS vb.	REST, GraphQL, gRPC, SOAP, WebSocket
Arayüz	CLI + ticari Studio/Insights	Görsel uygulama + apidog run CLI
İşlevsel/uçtan uca akışlar	Daha sınırlı; sözleşme senaryolarına odaklı	Güçlü: zincirlenmiş adımlar, veri odaklı çalıştırmalar, assertion'lar
Açık kaynak	Evet, çekirdek	Ücretsiz katman; platform ticari
En iyi olduğu alan	Bağımsız servisleri ortak sözleşmeye göre doğrulamak	API'yi yaşam döngüsü boyunca tasarlamak, mocklamak ve test etmek

Hangi durumda hangisini seçmelisiniz?

Specmatic'i seçin: ekipler arası sözleşme ana probleminizse

Şu tablo size tanıdık geliyorsa Specmatic daha uygun olabilir:

• Birden fazla mikroservis var.
• Servislerin sahipleri farklı ekipler.
• Tüketici ve sağlayıcı servisler bağımsız dağıtılıyor.
• Küçük schema değişiklikleri başka servisleri kırabiliyor.
• CI'da “bu servis sözleşmeye sadık mı?” kapısı istiyorsunuz.

Bu durumda Specmatic'in otomatik test üretimi ve stub olarak sözleşme yaklaşımı doğrudan ihtiyaca karşılık gelir.

Apidog CLI'ı seçin: tasarımdan CI'a tek akış istiyorsanız

Şu akışa ihtiyacınız varsa Apidog daha uygun olabilir:

1. OpenAPI tanımını oluştur.
2. Backend hazır olmadan mock servis aç.
3. Frontend veya tüketici ekipleri mock'a bağla.
4. İşlevsel test senaryoları oluştur.
5. Testleri her commit veya release öncesi CI'da çalıştır.
6. Aynı projede dokümantasyon, test ve mock bilgisini tut.

Bu durumda Apidog, ayrı bir tasarım aracı, ayrı bir mock aracı ve ayrı bir test runner arasında geçiş yapmanızı azaltır.

REST dışı protokoller için de aynı iş akışını kullanmak istiyorsanız Apidog pratik bir seçenek olabilir. Tasarım, mock ve doğrulamanın nasıl hizalandığını görmek için sözleşme testi ve mock sunucuları kılavuzuna bakabilirsiniz.

Hızlı karar matrisi

Aşağıdaki cümlelerden hangisi probleminizi daha iyi anlatıyor?

“Servislerimiz birbirinin sözleşmelerini bozuyor.”

Specmatic'e daha yakından bakın.

“Bu API'yi daha hızlı tasarlamamız, mocklamamız, test etmemiz ve CI'da çalıştırmamız gerekiyor.”

Apidog CLI daha uygun olabilir.

“İkisi de doğru.”

OpenAPI dosyasını ortak doğruluk kaynağı yapıp iki aracı birlikte kullanmak mantıklı olabilir.

Birlikte kullanabilir misiniz?

Evet. Hatta bazı ekipler için en dengeli kurulum budur.

Örnek mimari:

OpenAPI dosyası
   |
   |-- Apidog
   |     |-- API tasarımı
   |     |-- Mock servis
   |     |-- İşlevsel test senaryoları
   |     |-- apidog run ile CI
   |
   |-- Specmatic
         |-- Provider contract verification
         |-- Consumer stub/service virtualization

Pratik akış:

1. OpenAPI dosyasını ortak doğruluk kaynağı olarak belirleyin.
2. Apidog'da API'yi tasarlayın veya içe aktarın.
3. Mock sunucuyu tüketici ekiplerin kullanımına açın.
4. İşlevsel test senaryolarını Apidog'da oluşturun.
5. CI'da apidog run ile bu testleri çalıştırın.
6. Bağımsız servisler arasında daha sıkı sözleşme doğrulaması gereken noktalara Specmatic ekleyin.

Bu şekilde Apidog yaşam döngüsü kapsamını genişletir; Specmatic ise ekipler arası sözleşme kapısını güçlendirir.

Sıkça sorulan sorular

Apidog, Specmatic'e alternatif midir?

Bazı kullanım alanlarında evet; her durumda bire bir alternatif değildir.

API'yi spesifikasyondan tasarlamak, mocklamak, işlevsel testler oluşturmak ve CI'da çalıştırmak istiyorsanız Apidog bu alanı kapsar. Ancak tüketici ve sağlayıcı arasında özel bir sözleşme doğrulama akışı kurmak istiyorsanız Specmatic bu probleme daha odaklıdır.

En doğru tanım: İkisi de önce spesifikasyon yaklaşımındadır, fakat ağırlık merkezleri farklıdır.

Apidog CLI sözleşme testi yapar mı?

Apidog, test çalıştırmalarında API yanıtlarını OpenAPI şemanıza göre doğrulayabilir. Bu, spesifikasyon ile uygulama arasındaki yapısal sapmaları yakalar.

Ancak Apidog CLI, ayrı tüketici ve sağlayıcı repoları arasında Pact tarzı bir sözleşme aracısı gibi davranmaz. Schema doğrulamasının nerede bittiğini ve aracı tarzı sözleşmelerin nerede başladığını anlamak için API sözleşme testinin ne olduğuna dair açıklamaya bakabilirsiniz.

Hangisi CI/CD'ye daha iyi uyar?

İkisi de CI'da başsız çalışabilir.

• Specmatic: Spesifikasyondan sözleşme testleri üretir ve sağlayıcıyı doğrular.
• Apidog CLI: Apidog'da oluşturduğunuz görsel test senaryolarını apidog run ile çalıştırır.

CI geçidiniz şuysa Specmatic daha uygundur:

Servis, paylaşılan sözleşmeye uyuyor mu?

CI geçidiniz şuysa Apidog daha uygundur:

Bu API'nin işlevsel test paketi başarıyla geçiyor mu?

Test kodu yazmam gerekir mi?

Çoğunlukla hayır.

Specmatic, spesifikasyondan testler üretir. Bu yüzden sözleşme senaryolarını tek tek yazmanız gerekmez.

Apidog ise görsel test senaryoları, assertion'lar ve veri odaklı çalıştırmalar kullanır. Bu nedenle klasik test framework'lerinde olduğu gibi yoğun test kodu yazmak yerine testleri yapılandırırsınız.

Sonuç

Specmatic ve Apidog CLI aynı noktadan, yani spesifikasyondan başlar; fakat farklı problemlere odaklanır.

• Specmatic, kod olarak sözleşme için daha keskin bir araçtır. Sağlayıcıyı sözleşmeye göre doğrular ve tüketiciler için sanallaştırılmış servis sağlayabilir.
• Apidog CLI, daha geniş bir API yaşam döngüsü aracıdır. API'yi tasarlama, mocklama, işlevsel test yazma ve CI'da apidog run ile çalıştırma akışını tek yerde toplar.

Kararınızı darboğaza göre verin:

• Darboğazınız ekipler arası sözleşme kırılmalarıysa Specmatic.
• Darboğazınız API'yi hızlı tasarlamak, mocklamak ve testleri CI'a almaksa Apidog CLI.
• İki problem de varsa, OpenAPI dosyasını ortak kaynak yaparak ikisini birlikte kullanabilirsiniz.

Tek bir platformda önce spesifikasyon, mock ve CI'a hazır test iş akışı istiyorsanız Apidog'u indirin veya Apidog'un API yaşam döngüsünde neler sunduğunu keşfedin.