Swagger/OpenAPI ve Postman'dan yük testi oluşturma

Algebran Yazılım & Danışmanlık · Yayın 5 Ekim 2026

Çoğu ekibin elinde API'sini anlatan bir Swagger/OpenAPI dokümanı ya da her gün kullandığı bir Postman koleksiyonu vardır. Endpoint'ler, parametreler, örnek body'ler ve kimlik doğrulama şekli orada zaten yazılıdır; yük testini sıfırdan yazmak yerine bunlardan başlamak saatler kazandırır. Ama doküman bir API'nin neler yapabildiğini anlatır, kullanıcıların nasıl davrandığını değil. Bu rehber dokümandan neyin otomatik gelebileceğini, neyi elle tamamlamanız gerektiğini ve değişkenlerle ortamları nasıl kuracağınızı anlatıyor.

Dokümandan ne gelir?

• İstekler: her operasyon için metot, yol ve sunucu adresi. OpenAPI'de servers, Swagger 2.0'da host ve basePath, Postman'de istek URL'leri.
• Parametreler ve body'ler: path ve query parametreleri, zorunlu header'lar, JSON ya da form body'ler. Dokümanda example varsa o kullanılır; yoksa şemadan bir örnek değer türetilir.
• Kimlik doğrulama: bearer token, basic auth ya da header veya query'deki API anahtarı. Değerin kendisi dokümanda yoktur (olmamalı); yalnız şekli gelir.
• Beklenen yanıt: dokümanın başarılı saydığı status kodu (200, 201…), en basit kontrol olarak.

Doküman neyi bilmez?

Dokümandaki her endpoint'i birer kez çağıran bir test, kullanıcılarınızın yaptığı şeye benzemez. Şunları siz eklersiniz:

• Akış ve oranlar. Gerçek trafikte listeleme ve detay istekleri sipariş oluşturmaktan kat kat fazladır. Yalnız önemli akışları seçin, sırasını kurun (giriş, arama, detay, sepet) ve canlıdaki oranlara yakın tutun.
• Korelasyon. Bir isteğin yanıtındaki değer (giriş token'ı, yeni siparişin id'si) sonraki isteklerde kullanılır. Doküman bu bağı bilmez; yanıttan değer çıkarmayı (JSONPath gibi) siz tanımlarsınız.
• Gerçekçi veri. Her istekte aynı örnek id önbellekten döner ve sistemi olduğundan hızlı gösterir. Id'leri ve kullanıcıları bir veri dosyasından ya da üreteçlerden alın.
• Yük modeli ve düşünme süresi. Kaç kullanıcı, hangi hızda, ne kadar süre, istekler arasında kaç saniye (yük testi türleri).

Veri değiştiren istekler

Bir dokümanın bütün operasyonlarını toptan teste çevirmek tehlikelidir: yük testi her iterasyonda bütün POST, PUT ve DELETE isteklerini tekrarlar. Yanlış ortama karşı koşturulan bir test binlerce kayıt oluşturabilir ya da silebilir. Okuma isteklerinden başlayın, yazma isteklerini bilerek ve tek tek ekleyin, hedefin bir test ortamı olduğundan emin olun.

Değişkenler ve ortamlar

Aynı test staging'e, pre-prod'a ve gerekirse canlıya karşı koşar; değişen yalnız adres, token ve birkaç değerdir. Bunları isteklerin içine gömmeyin: temel adresi, token'ı ve ortamdan ortama değişen her şeyi bir değişken yapın, ortam başına değerlerini ayrı tutun. Postman kullanıcıları bunu koleksiyon değişkenleri ve environment'lar olarak bilir; yük testinde de aynı düzen işe yarar. Gizli değerleri (token, parola) test tanımına değil, aracın gizli değer kasasına ya da pipeline secret'ına koyun.

Spitfire ile

Testler → API / HAR içe aktar'da dokümanın adresini verin ya da dosyayı yükleyin: OpenAPI 3.x, Swagger 2.0 veya Postman koleksiyonu v2.0/v2.1 (JSON ya da YAML, en çok 10 MB). Operasyonlar etiketlerine (Postman'de klasörlerine) göre listelenir; yol, özet ya da etiketle arayıp seçersiniz. Seçtiğiniz her operasyon bir adım olur.

• Temel adres: dokümandaki sunuculardan biri seçili gelir; yerine test ortamınızın adresini yazabilirsiniz. Testte {{base}} değişkeni olur.
• Parametreler: path parametreleri değişken olur ({{orderId}}) ve dokümandaki örnek değeri alır; query parametrelerinden zorunlu olanlar ya da dokümanda değeri verilenler, header'lardan zorunlu olanlar gelir. JSON body dokümandaki örnekten ya da şemadan üretilir.
• Kimlik doğrulama: bearer (OAuth2 ve OpenID Connect dahil) Authorization: Bearer {{token}}, basic auth {{basicAuth}}, API anahtarı header'da ya da query'de {{apiKey}} olur. Bu değişkenler boş gelir; değerlerini editörde girersiniz.
• Postman: koleksiyonun değişkenleri testin değişkenleri olur, :id gibi path değişkenleri {{id}}'ye çevrilir, koleksiyon ve klasör auth'u isteklere geçer. {{$guid}}, {{$timestamp}}, {{$randomInt}} gibi dinamik değişkenler Spitfire karşılıklarına çevrilir, karşılığı olmayanlar sabit bir örnek değer olur. Postman environment dosyaları ile pre-request ve test script'leri içe aktarılmaz; environment değerlerini testin Ortamlar sekmesine girin.
• Kontrol ve yük: her adıma dokümandaki başarılı status kodu için bir kontrol eklenir. Test 1 VU ile 1 dakikalık bir başlangıç olarak oluşur; yük modelini siz kurarsınız.

Yazma istekleri: varsayılan olarak yalnız GET istekleri seçilir. POST, PUT/PATCH ve DELETE grupları seçime eklenirse her grup ayrı ayrı onaylanır ve hedef sunucunun adı bir kez yazılır; onay kullanıcı, zaman, IP, dokümanın SHA-256 özeti ve işlem listesiyle denetim kaydına geçer. Bu adımlar veri değiştiren adım olarak işaretlenir ve testin her koşusu başlamadan yeniden yazma onayı ister.

openapi: 3.0.3
info: { title: Shop API, version: "1.0" }
servers: [ { url: https://staging.shop.example.com/api } ]
components:
  securitySchemes: { bearerAuth: { type: http, scheme: bearer } }
security: [ { bearerAuth: [] } ]
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      parameters:
        - { name: orderId, in: path, required: true,
            schema: { type: string }, example: "o-42" }
      responses: { "200": { description: ok } }

"variables": {
  "base": "https://staging.shop.example.com/api",
  "orderId": "o-42",
  "token": ""
},
"scenarios": [ { "name": "api",
  "executor": { "type": "constant-vus", "vus": 1, "duration": "1m0s" },
  "steps": [ { "id": "getorder", "name": "Get an order", "protocol": "http",
    "request": { "method": "GET", "url": "{{base}}/orders/{{orderId}}",
      "headers": [ { "key": "Authorization", "value": "Bearer {{token}}" } ] },
    "checks": [ { "type": "status", "op": "eq", "value": 200 } ] } ] } ]

Ardından editörde testi tamamlarsınız: giriş adımından token'ı JSONPath ile çıkarıp {{token}}'a bağlayın, id'leri bir CSV veri dosyasından alın, düşünme süresi ve eşikler ekleyin, yük modelini seçin. Ortamlar sekmesinde her ortam (staging, production…) kendi base, token ve diğer değerlerini verir; koşu ya da zamanlama başlatırken ortamı seçer, yükü ölçeklersiniz. Pipeline'dan: spitfire cloud run "Shop API" --env staging (CI/CD rehberi). Tarayıcıda kaydedilmiş bir HAR dosyası da aynı sayfadan içe aktarılır; orada token ve id'ler yanıttan otomatik değişkene bağlanır. Elinizde k6 betikleri varsa: k6 betiklerini içe aktarma.