Specmatic Nedir?

Eğer bir OpenAPI dosyanız var ama çalışan servisiniz zamanla bu sözleşmeden sapıyorsa, Specmatic bu farkı otomatik yakalamak için kullanılır. Specmatic, API şartnamenizi yürütülebilir bir sözleşme gibi ele alır: canlı servisi bu sözleşmeye göre test eder ve aynı dosyadan bir stub sunucu çalıştırır. Bu yazıda Specmatic’in ne yaptığını, örnek tabanlı testten nasıl ayrıldığını, CI’da nasıl çalıştırılacağını ve Apidog’un API sözleşme testi gibi daha geniş platform yaklaşımlarıyla nerede farklılaştığını göreceksiniz. Temel doğruluk kaynağı ise Specmatic’in okuduğu OpenAPI Specification dosyasıdır.

Apidog'u bugün deneyin

Specmatic nedir?

Specmatic, sözleşme odaklı geliştirme için açık kaynaklı bir araçtır. API sözleşmeniz bir OpenAPI YAML veya JSON dosyasıysa, Specmatic bu dosyayı iki şekilde kullanır:

• Canlı servisi test eder: Servisin OpenAPI’de tanımlanan path, HTTP durum kodu, request/response şeması ve zorunlu alanlara uyup uymadığını kontrol eder.
• Stub sunucu çalıştırır: Gerçek backend hazır olmasa bile tüketicilerin sözleşmeye uygun yanıtlar alan bir sahte servisle geliştirme yapmasını sağlar.

Avantajı şudur: ayrı bir test tanımı ve ayrı bir dokümantasyon dosyası tutmazsınız. Aynı OpenAPI dosyası hem test hem stub için kullanılır.

Specmatic yalnızca OpenAPI ile sınırlı değildir. Sürüm 2.0 ile GraphQL ve gRPC desteği eklenmiştir; ayrıca AsyncAPI, WSDL ve Avro gibi formatları da destekler. Yine de çoğu ekip için başlangıç noktası bir OpenAPI dosyasıdır.

CLI veya Docker ile çalıştırabilirsiniz. Bu nedenle CI/CD pipeline’larına eklemek kolaydır.

Sözleşme testi ile örnek tabanlı test farkı

Örnek tabanlı testte belirli istekler yazarsınız ve bu isteklere gelen yanıtları doğrularsınız. Örneğin:

curl http://localhost:8080/users/1

Ardından beklenen durum kodunu veya birkaç alanı kontrol edersiniz. Bu yaklaşım pratik olsa da kapsam sizin yazdığınız örneklerle sınırlıdır.

Sözleşme testinde ise doğrulama kaynağı OpenAPI dosyasıdır. Specmatic şemayı okur ve servisin bu sözleşmeye uyup uymadığını kontrol eder. Örneğin:

• Yanıt gövdesi OpenAPI şemasına uyuyor mu?
• Zorunlu alanlar gerçekten dönüyor mu?
• Tanımlanan HTTP durum kodlarıyla servis davranışı eşleşiyor mu?
• Geçersiz istekler sözleşmenin ima ettiği şekilde reddediliyor mu?

Yön	Örnek tabanlı test	Specmatic ile sözleşme testi
Doğruluk kaynağı	El yazımı test senaryoları	OpenAPI şartnamesi
Sürdürdüğünüz şey	Her istek ve doğrulama	Zaten tuttuğunuz sözleşme dosyası
Kapsam	Sadece yazdığınız örnekler	Şartnamenin tanımladığı işlemler
Sapma tespiti	Manuel	Otomatik
Tipik hata	Belirli bir örnek bozulur	Servis sözleşmeyle eşleşmez

Burada Pact ile karıştırmamak gerekir. Pact tüketici odaklı sözleşme testine odaklanır: tüketiciler beklentilerini yayınlar, sağlayıcılar bunlara göre doğrulanır. Specmatic ise sözleşme odaklıdır: OpenAPI dosyası iki tarafın paylaştığı tek sözleşmedir.

Daha geniş araç karşılaştırması için API sözleşme testi ve mocking araçları rehberine bakabilirsiniz.

Specmatic nasıl çalıştırılır?

Specmatic’i yerel CLI olarak veya Docker ile çalıştırabilirsiniz. CI ortamlarında Docker kullanmak genellikle daha pratiktir çünkü ek runtime kurulumu gerektirmez.

1. OpenAPI dosyanızı hazırlayın

Basit bir api.yaml dosyanız olduğunu varsayalım:

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - name
                properties:
                  id:
                    type: integer
                  name:
                    type: string

Specmatic bu dosyayı okuyarak canlı servisin bu sözleşmeye uyup uymadığını test eder.

2. Canlı servise karşı sözleşme testi çalıştırın

Servisiniz http://localhost:8080 üzerinde çalışıyorsa:

# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080

Docker ile çalıştırmak için:

docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080

Bu komut şunları yapar:

1. api.yaml dosyasını okur.
2. OpenAPI’de tanımlanan operasyonlardan test istekleri üretir.
3. İstekleri çalışan servise gönderir.
4. Yanıtları sözleşmedeki şemalarla karşılaştırır.

Test başarısızsa iki ihtimal vardır:

• Servis gerçekten sözleşmeden sapmıştır.
• OpenAPI dosyası güncel değildir.

Her iki durumda da düzeltmeniz gereken yer netleşir.

3. Aynı şartnameyi stub sunucu olarak çalıştırın

Tüketici ekiplerin backend beklemeden geliştirme yapması için aynı OpenAPI dosyasından stub başlatabilirsiniz:

specmatic stub api.yaml --port=9000

Artık tüketici uygulamalarını şu adrese yönlendirebilirsiniz:

http://localhost:9000

Specmatic, OpenAPI şemasına uygun yanıtlar üretir. İsterseniz şartnamenin yanında _examples dizini kullanarak daha somut örnek yanıtlar da sağlayabilirsiniz. İstek eşleştiğinde stub bu örnekleri döndürür.

Mock ve stub yaklaşımlarını karşılaştırmak isterseniz sözleşme testi ve mock server özetine göz atabilirsiniz.

Tipik geliştirme akışı

Specmatic’i en verimli kullanan ekiplerde akış genellikle şöyledir:

1. API sözleşmesi OpenAPI dosyasında tanımlanır.
2. Sağlayıcı ekip servisi bu sözleşmeye göre geliştirir.
3. CI’da specmatic test çalışır.
4. Tüketici ekipler specmatic stub ile aynı sözleşmeye karşı geliştirme yapar.
5. Sözleşme değişirse hem test hem stub aynı dosyadan güncellenir.

Örnek CI adımı:

name: Contract Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  specmatic:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Start API
        run: |
          docker compose up -d api

      - name: Run Specmatic contract tests
        run: |
          docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
            test api.yaml --testBaseURL=http://host.docker.internal:8080

Bu yapı sayesinde API kodu OpenAPI dosyasından saparsa pull request aşamasında yakalanır.

Şartnameyi hem sözleşme hem stub olarak kullanmak neden önemli?

Aynı OpenAPI dosyasını hem test hem stub için kullanmak senkronizasyon problemini azaltır.

• Sağlayıcı ekip specmatic test ile gerçek servisi doğrular.
• Tüketici ekip specmatic stub ile sözleşmeye uygun sahte servis kullanır.
• İki taraf da aynı API davranışını referans alır.

Böylece OpenAPI dosyası sadece dokümantasyon değil, çalışan bir anlaşma haline gelir.

Stub ve mock farkını daha net anlamak için API stubbing ve mocking konusundaki temel farklara bakabilirsiniz.

Geriye dönük uyumluluk kontrolü

Specmatic ayrıca geriye dönük uyumluluk kontrolü de yapabilir. backward-compatibility-check komutu, yeni sözleşmenin eski sözleşmeye göre uyumlu kalıp kalmadığını test etmek için kullanılır.

Genel fikir:

1. Yeni sözleşmeden bir stub başlatılır.
2. Eski sözleşmeden testler üretilir.
3. Eski davranışların yeni sözleşmede hâlâ çalışıp çalışmadığı kontrol edilir.

Bu, özellikle bağımsız dağıtılan mikro servislerde önemlidir. Eski tüketicileri bozacak bir değişikliği deploy öncesinde yakalamanızı sağlar.

Bu yaklaşım, çift yönlü sözleşme testi kapsamında ele alınan daha geniş fikrin bir parçasıdır.

Mevcut servisten OpenAPI üretmek

Her ekip API geliştirmeye hazır bir OpenAPI dosyasıyla başlamaz. Specmatic bu durumda proxy olarak çalışabilir:

• Mevcut servisin önüne konumlanır.
• Gerçek istek ve yanıt trafiğini gözlemler.
• Gördüğü davranışlardan OpenAPI belgesi ve örnek dosyalar oluşturabilir.

Bu, çalışan bir servisiniz varsa ancak resmi API sözleşmeniz henüz yoksa başlangıç noktası sağlar.

Specmatic ne zaman iyi seçimdir?

Specmatic şu durumlarda güçlü bir tercihtir:

• OpenAPI, AsyncAPI, GraphQL veya gRPC sözleşmeniz gerçek doğruluk kaynağıysa.
• Sağlayıcı ve tüketici ekipleriniz ayrı çalışıyorsa.
• API sözleşmesinden sapmaların CI’da otomatik yakalanmasını istiyorsanız.
• CLI ve pipeline odaklı bir iş akışınız varsa.
• API dokümantasyonunu pasif belge değil, çalıştırılabilir sözleşme olarak kullanmak istiyorsanız.

Daha az uygun olduğu durumlar:

• Henüz düzenli bir API şartnamesi tutmuyorsanız.
• API tasarımı, test, mock, dokümantasyon ve ekip işbirliği için görsel bir çalışma alanı arıyorsanız.
• Kodsuz kullanım ve ortak workspace sizin için CLI’dan daha önemliyse.

Specmatic dar kapsamlı ama net bir iş yapar: sözleşmeyi çalıştırılabilir hale getirir.

Specmatic ve Apidog nerede ayrılır?

Specmatic, CLI öncelikli bir sözleşme test aracıdır. OpenAPI dosyanızı okur, canlı servisi doğrular ve aynı dosyadan stub çalıştırır.

Apidog ise daha geniş bir API geliştirme çalışma alanıdır. OpenAPI şemasını okuyabilir, yanıtları şemaya göre doğrulayabilir ve kod yazmadan OpenAPI şemanızdan mock server başlatabilir.

Pratik fark şudur:

• Specmatic: CLI, CI ve sözleşme doğrulama odaklıdır.
• Apidog: API tasarımı, test, mock ve dokümantasyonu tek görsel çalışma alanında birleştirir.

Apidog da Pact tarzı tüketici odaklı bir broker değildir. Eğer ihtiyacınız özellikle pact broker ise, farklı bir araç seti gerekir.

OpenAPI dosyasından çalıştırılabilir testler üretmek istiyorsanız OpenAPI şartnamelerinden API test koleksiyonu oluşturma yaklaşımına bakabilirsiniz.

Sıkça sorulan sorular

Specmatic ücretsiz mi?

Evet. Temel sözleşme motoru açık kaynaklıdır ve CLI veya Docker ile ücretsiz kullanılabilir. Ticari teklifler de vardır, ancak OpenAPI sözleşmelerinden test ve stub çalıştırmak için açık kaynak sürümü kullanabilirsiniz. Güncel lisans ve ücretli özellikler için resmi siteyi ve GitHub reposunu kontrol etmek gerekir.

Specmatic sadece OpenAPI ile mi çalışır?

Hayır. OpenAPI en yaygın başlangıç noktasıdır, ancak Specmatic AsyncAPI, GraphQL, gRPC, WSDL ve Avro gibi formatları da destekler. Model aynıdır: şartname yürütülebilir sözleşmedir.

OpenAPI’ye yeni başlıyorsanız OpenAPI Specification eğitimi faydalı olabilir.

Specmatic, Pact ile aynı mı?

Tam olarak değil. Pact tüketici odaklıdır: tüketici beklentileri pact olarak yayınlanır ve sağlayıcılar bunlara göre doğrulanır.

Specmatic sözleşme odaklıdır: OpenAPI veya benzeri şartname tek paylaşılan sözleşmedir. Specmatic sağlayıcıyı bu sözleşmeye göre test eder ve tüketiciler için aynı sözleşmeden stub çalıştırır.

Specmatic benim için OpenAPI şartnamesi oluşturabilir mi?

Evet. Specmatic mevcut bir servisin önünde proxy olarak çalışabilir, gerçek istek ve yanıt trafiğini yakalayabilir ve buradan OpenAPI belgesi ile örnek dosyalar oluşturabilir. Bu, sözleşmesiz çalışan eski servisleri sözleşme odaklı akışa taşımak için kullanışlıdır.

Sonuç

Specmatic, çalışan bir servisin OpenAPI sözleşmesine gerçekten uyup uymadığını otomatik kontrol etmek için kullanışlıdır. Aynı şartnameden hem sözleşme testi hem stub sunucu çalıştırır; böylece API dokümanı pasif bir belge olmaktan çıkar ve CI’da doğrulanan canlı bir sözleşmeye dönüşür.

Eğer terminal ve CI merkezli çalışıyorsanız, Specmatic net bir çözümdür. Eğer sözleşme, test, mock ve dokümantasyonu aynı görsel çalışma alanında yönetmek istiyorsanız, Apidog’u deneyin. Yanıtları şemaya göre doğrulayabilir, endpoint’leri kodsuz taklit edebilir ve OpenAPI şartnamelerini çalıştırılabilir test koleksiyonlarına dönüştürebilirsiniz. Apidog’u indirin, şartnamenizi içe aktarın ve tasarımdan teste akışı tek yerde yönetin.