DEV Community

Cover image for En İyi OpenAPI Doğrulama Araçları: Temiz API Spesifikasyonları
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

En İyi OpenAPI Doğrulama Araçları: Temiz API Spesifikasyonları

Bir OpenAPI belirtimi bir sözleşmedir. Kod üreteçleri, belgeler, sahte sunucular ve istemci SDK’leri bu dosyayı kaynak kabul eder. Belirtim hatalıysa, bu hatayı tüm alt çıktılara taşırsınız. Bu yüzden OpenAPI doğrulamasını tek seferlik bir kontrol değil, geliştirme akışının parçası olarak ele almak gerekir.

Apidog'u bugün deneyin

Bu yazıda kullanmaya değer OpenAPI doğrulayıcılarını, hangi problemi çözdüklerini ve bunları gerçek bir geliştirme akışına nasıl yerleştirebileceğinizi ele alacağız. Bazı araçlar ham sözdizimini ve şema uyumluluğunu kontrol eder. Bazıları ise stil, tutarlılık ve API tasarım kurallarını uygular. Sağlam kurulum genellikle ikisini birlikte kullanır.

Belirtimi doğrulamanın önemi

OpenAPI doğrulamasında iki ayrı kontrol türü vardır:

  1. Doğruluk kontrolü
  2. Kalite ve stil kontrolü

Doğruluk kontrolü şu soruya cevap verir:

Bu dosya geçerli bir OpenAPI belirtimi mi?

Örneğin:

  • YAML girintisi bozuk mu?
  • $ref var olmayan bir şemaya mı işaret ediyor?
  • Zorunlu bir alan eksik mi?
  • Yol parametresi tanımlanmadan mı kullanılmış?
  • Şema tipi hatalı mı yazılmış?

Bunlar nesnel hatalardır. Dosya ya OpenAPI şemasına göre geçerlidir ya da değildir.

Kalite kontrolü ise şunu sorar:

Belirtim geçerli, ama tüketilebilir ve tutarlı mı?

Örneğin:

  • Her endpoint için summary veya description var mı?
  • operationId değerleri tutarlı mı?
  • Hata yanıtları belgelenmiş mi?
  • Güvenlik gereksinimleri açıkça belirtilmiş mi?
  • Path adlandırmaları aynı standardı takip ediyor mu?

Bunlar OpenAPI şeması tarafından her zaman zorunlu tutulmaz, ancak iyi bir API tüketici deneyimi için kritiktir. Bu ayrım, daha geniş anlamda API sözleşme testi yaklaşımının da temelidir: hatayı üretime veya SDK üretimine gitmeden önce yakalamak.

Bilmeye değer OpenAPI doğrulayıcı araçları

Swagger Editor

Swagger Editor, OpenAPI projesinin resmi tarayıcı tabanlı düzenleyicisidir.

Kullanım şekli basittir:

  1. OpenAPI YAML veya JSON dosyanızı editöre yapıştırın.
  2. Sağ panelde canlı önizlemeyi kontrol edin.
  3. Sol panelde doğrulama hatalarını anında görün.
  4. Hataları düzeltip tekrar kontrol edin.

Swagger Editor özellikle şu işler için uygundur:

  • Hızlı sözdizimi kontrolü
  • Yeni bir belirtim yazarken canlı geri bildirim
  • Küçük değişiklikleri manuel doğrulama
  • Ekip içi hızlı inceleme

CI/CD için ideal araç değildir, çünkü temel kullanım senaryosu tarayıcı üzerindedir. Ancak geliştirme sırasında en hızlı ilk kontrol noktalarından biridir.

Spectral

Spectral, Stoplight tarafından geliştirilen açık kaynaklı bir linter’dır. OpenAPI ve AsyncAPI için kural setleri sağlar.

Spectral’in güçlü tarafı özel kural yazabilmenizdir. Örneğin ekibiniz şu kuralları zorunlu kılabilir:

  • Her endpoint operationId içermeli
  • Her endpoint summary içermeli
  • Path sonunda / kullanılmamalı
  • Tüm hata yanıtları belgelenmeli
  • Tag kullanımı zorunlu olmalı

Basit kurulum:

npm install -g @stoplight/spectral-cli
Enter fullscreen mode Exit fullscreen mode

Bir OpenAPI dosyasını lint etmek için:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Örnek .spectral.yaml:

extends: ["spectral:oas"]

rules:
  operation-summary:
    description: Her operasyon summary alanı içermeli
    given: "$.paths[*][*]"
    then:
      field: summary
      function: truthy

  no-trailing-slash:
    description: Path sonunda slash kullanılmamalı
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "/$"
Enter fullscreen mode Exit fullscreen mode

CI içinde çalıştırmak için:

spectral lint openapi.yaml --fail-severity=warn
Enter fullscreen mode Exit fullscreen mode

Spectral, tasarım kurallarını otomatikleştirmek isteyen ekipler için en pratik seçeneklerden biridir.

openapi-spec-validator

openapi-spec-validator, Python tabanlı odaklı bir doğrulama aracıdır. Temel görevi şudur:

OpenAPI dosyası resmi OpenAPI şemasına göre geçerli mi?

OpenAPI 2.0, 3.0 ve 3.1 sürümlerini destekler. Stil veya tasarım hakkında görüş belirtmez. Sadece yapısal doğruluğu kontrol eder.

Kurulum:

pip install openapi-spec-validator
Enter fullscreen mode Exit fullscreen mode

Kullanım:

openapi-spec-validator openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Python içinde kullanmak isterseniz:

from openapi_spec_validator import validate
from openapi_spec_validator.readers import read_from_filename

spec_dict, base_uri = read_from_filename("openapi.yaml")
validate(spec_dict)
Enter fullscreen mode Exit fullscreen mode

Bu araç özellikle şunlar için uygundur:

  • Python tabanlı build adımları
  • Pre-commit hook’ları
  • CI’da kesin geçiş/hata kapısı
  • Sadece şema doğruluğu kontrolü gereken durumlar

Örnek pre-commit yapılandırması:

repos:
  - repo: local
    hooks:
      - id: openapi-validate
        name: Validate OpenAPI spec
        entry: openapi-spec-validator openapi.yaml
        language: system
        files: openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog

Apidog, OpenAPI doğrulamasını API tasarım akışının içine yerleştirir. Bir OpenAPI tanımı oluşturduğunuzda veya içe aktardığınızda, düzenleyici içinde yapısal sorunları işaretler.

Apidog’un öne çıkan tarafı çalışma zamanı doğrulamasıdır. Yani yalnızca dosyanın geçerli olup olmadığını değil, canlı API yanıtlarının belirtimdeki şemayla eşleşip eşleşmediğini de kontrol edebilirsiniz.

Bu ayrım önemlidir:

  • OpenAPI dosyanız geçerli olabilir.
  • Ancak gerçek API yanıtı belirtimden sapmış olabilir.

Örneğin belirtimde yanıt şöyle tanımlanmış olabilir:

User:
  type: object
  required:
    - id
    - email
  properties:
    id:
      type: integer
    email:
      type: string
Enter fullscreen mode Exit fullscreen mode

Ancak canlı API şu yanıtı dönebilir:

{
  "id": "123",
  "email_address": "dev@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Bu durumda belirtim geçerli olsa bile uygulama sözleşmeye uymuyordur. Apidog bu tür sapmaları yakalamaya yardımcı olur. Belirtimleri tek bir araçta tasarlamak ve doğrulamak için Apidog'u indirin.

Redocly CLI

Redocly CLI; linting, doğrulama ve belge oluşturmayı aynı araç zincirinde birleştirir.

Temel kullanım alanları:

  • OpenAPI şema doğrulaması
  • Stil ve kalite kuralları
  • Çok dosyalı belirtimleri tek dosyada paketleme
  • Redoc tabanlı belge üretim akışları

Kurulum:

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode

Lint çalıştırmak için:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Çok dosyalı bir belirtimi paketlemek için:

redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Redoc ile belge üreten ekipler için Redocly CLI doğal bir seçimdir, çünkü doğrulama ve dokümantasyon aynı ekosistemde kalır.

Vacuum

Vacuum, Go ile yazılmış hızlı bir OpenAPI linter’ıdır. Özellikle büyük belirtimlerde performans avantajı sağlar.

Kullanım senaryoları:

  • Büyük OpenAPI dosyaları
  • Monorepo içinde çok sayıda API belirtimi
  • CI süresinin kritik olduğu projeler
  • Spectral tarzı kurallar kullanan ekipler

Vacuum, Spectral benzeri kurallarla uyumludur. Bu nedenle mevcut lint yaklaşımından geçiş yapmak genellikle düşük maliyetlidir.

Karşılaştırma tablosu

Araç Tür Kontrol Ettiği CI'da Çalışır En İyi Kullanım
Swagger Editor Tarayıcı düzenleyici Sözdizimi, şema Hayır Canlı düzenleme ve hızlı kontroller
Spectral CLI linter Stil, özel kurallar Evet Tasarım kurallarını uygulama
openapi-spec-validator CLI / Python kütüphanesi Şema doğruluğu Evet Kesin geçiş veya hata kapısı
Apidog Entegre platform Şema + çalışma zamanı sapması Evet Tasarım ve yanıt doğrulama
Redocly CLI CLI Şema, stil, paketleme Evet Belgeler ve doğrulama bir arada
Vacuum CLI linter Stil, Spectral kuralları Evet Çok büyük belirtimler ve hız

Bir doğrulama iş akışı nasıl oluşturulur

Tek bir araç seçmek yerine doğrulamayı katmanlı kurmak daha sağlıklıdır.

Önerilen akış:

  1. Editör seviyesinde hızlı doğrulama
  2. CI’da şema doğrulaması
  3. CI’da lint ve kalite kontrolü
  4. Çalışan API için sözleşme doğrulaması

1. Yazarken doğrulayın

Belirtimi yazarken Swagger Editor veya entegre bir API tasarım aracı kullanın. Amaç, bariz hataları daha dosya commit edilmeden yakalamaktır.

Örneğin şu hata editör seviyesinde hemen görünmelidir:

paths:
  /users/{id}:
    get:
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

Burada {id} path içinde kullanılmıştır, ancak parameters altında tanımlanmamıştır.

Düzeltilmiş hali:

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

2. CI’da doğruluk kapısı ekleyin

Her pull request’te OpenAPI dosyasını doğrulayın. Dosya OpenAPI şemasına göre geçerli değilse build başarısız olmalıdır.

GitHub Actions örneği:

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install validator
        run: pip install openapi-spec-validator

      - name: Validate spec
        run: openapi-spec-validator openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Bu kontrol pazarlık konusu olmamalıdır. Geçersiz belirtim merge edilmemelidir.

3. CI’da kalite kapısı ekleyin

Şema doğrulaması dosyanın geçerli olduğunu söyler. Ancak API tasarımının tutarlı olduğunu söylemez. Bunun için Spectral veya Vacuum gibi bir linter kullanın.

GitHub Actions içinde Spectral örneği:

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"
      - ".spectral.yaml"

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli

      - name: Lint spec
        run: spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Başlangıç için yerleşik OpenAPI kurallarını kullanın. Sonra ekibinizin standartlarına göre özel kurallar ekleyin.

Bu yaklaşım, CI/CD'de testleri otomatikleştirmeyi güvenilir kılan aynı prensibe dayanır: kontrol, biri hatırladığında değil, her değişiklikte çalışır.

4. Çalışan API’yi belirtime göre doğrulayın

Belirtim doğru olabilir, ancak uygulama ondan sapmış olabilir. Bu yüzden çalışma zamanı doğrulaması veya sözleşme testi ekleyin.

Kontrol edilmesi gerekenler:

  • Yanıt gövdesi belirtimdeki şemaya uyuyor mu?
  • Zorunlu alanlar dönüyor mu?
  • Alan tipleri doğru mu?
  • Hata yanıtları belgelenen formatta mı?
  • Status code’lar belirtimle uyumlu mu?

Apidog üzerinden veya test paketinizde sözleşme testleriyle bu kontrolü çalıştırabilirsiniz. Test tarafında faydalı API iddiaları yazmak, yanıtların belgelenmiş şemaya göre nasıl kontrol edileceğini açıklar.

Yaygın hata: belirtimi yalnızca bir kez doğrulamak

Birçok ekip OpenAPI belirtimini ilk yazdığında doğrular, sonra bir daha kontrol etmez. Bu noktadan sonra belirtim yavaşça çürür.

Tipik senaryo:

  1. Geliştirici yeni endpoint ekler.
  2. Kod güncellenir.
  3. OpenAPI dosyası unutulur.
  4. Belgeler eski kalır.
  5. SDK yanlış üretilir.
  6. Tüketici ekipler hatalı sözleşmeye göre entegrasyon yapar.

Bunu önlemek için doğrulamayı sürekli hale getirin:

  • Her pull request’te çalıştırın.
  • Belirtim değiştiğinde zorunlu hale getirin.
  • API davranışı değiştiğinde sözleşme testlerini çalıştırın.
  • Hatalı belirtimi başarısız bir birim testi gibi ele alın.

Bu, otomatik test yaklaşımıyla aynı mantığa sahiptir: kontrol, manuel karar gerektirmeden çalıştığında değerlidir.

OpenAPI sürümünü açıkça doğrulayın

OpenAPI 3.0 ve 3.1 arasında özellikle JSON Schema uyumluluğu açısından önemli farklar vardır. OpenAPI 3.1, JSON Schema ile daha uyumlu hale gelmiştir ve bazı şema davranışları değişmiştir.

Bu nedenle:

  • Belirtimde openapi sürümünü açıkça yazın.
  • Doğrulayıcınızın bu sürümü desteklediğinden emin olun.
  • Araç varsayılanlarını kontrol edin.
  • CI’da kullanılan doğrulayıcı sürümünü sabitleyin.

Örnek:

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
Enter fullscreen mode Exit fullscreen mode

Araçlarınız 3.0 varsayıyor ama belirtiminiz 3.1 kullanıyorsa yanlış pozitif veya yanlış negatif sonuçlar alabilirsiniz. Resmi OpenAPI Belirtimi, sürüm farklarını belgeler.

Doğrulayıcıların yakaladığı tipik hatalar

“Belirtim yanlış” ifadesi tek başına yeterince aksiyon alınabilir değildir. Doğrulayıcıların yakaladığı hata tiplerini net görmek daha faydalıdır.

Yapısal hatalar

Örnek hatalar:

  • Var olmayan şemaya giden $ref
  • Eksik description
  • Tanımlanmamış path parametresi
  • Yanlış veri tipi
  • Geçersiz responses yapısı
  • Hatalı YAML girintisi

Hatalı örnek:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: int
Enter fullscreen mode Exit fullscreen mode

Burada int geçerli bir OpenAPI tipi değildir. Doğrusu:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
Enter fullscreen mode Exit fullscreen mode

Başka bir örnek:

paths:
  /users/{userId}:
    get:
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

Bu belirtimde userId path parametresi tanımlanmamıştır. Doğrusu:

paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

Bu tür hatalar kod üreticilerini bozabilir veya hatalı SDK üretilmesine neden olabilir.

Kalite hataları

Kalite hataları genellikle ayrıştırıcıyı bozmaz, ancak API tüketimini zorlaştırır.

Örnekler:

  • operationId eksik
  • Bazı path’ler snake_case, bazıları camelCase
  • Sadece 200 yanıtı belgelenmiş
  • 400, 401, 404 gibi hata yanıtları yok
  • Gerçekte zorunlu olan request body isteğe bağlı gösterilmiş
  • Endpoint açıklamaları yetersiz
  • Tag kullanımı tutarsız

Eksik örnek:

paths:
  /users:
    post:
      summary: Create user
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

Daha iyi örnek:

paths:
  /users:
    post:
      operationId: createUser
      summary: Create user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: User created
        "400":
          description: Invalid request
        "401":
          description: Unauthorized
Enter fullscreen mode Exit fullscreen mode

Bu kalite çizgisini koruyan araç linter’dır. Gerçek davranışın belirtimle uyumlu kalmasını ise API sözleşme testi doğrular.

Tasarıma öncelik veren iş akışında doğrulama

Birçok ekip artık API’yi önce OpenAPI belirtimiyle tasarlıyor. Sonra bu belirtimden şunlar üretiliyor:

  • Sunucu taslakları
  • Mock API’ler
  • Belgeler
  • SDK’ler
  • Test senaryoları

Bu modelde OpenAPI dosyası yalnızca dokümantasyon değildir. Sistemin doğruluk kaynağıdır.

Bu yüzden tasarım öncelikli akışta doğrulama şu noktalarda çalışmalıdır:

  1. Tasarım sırasında

    • Editör içinde canlı doğrulama
    • Hatalı şema veya eksik alanları erken yakalama

  2. Pull request sırasında

    • Şema doğrulaması
    • Lint kuralları
    • Ekip standartları

  3. Mock üretiminden önce

    • Mock sunucunun yanlış sözleşmeden üretilmesini engelleme

  4. Uygulama testlerinde

    • Gerçek API’nin belirtime uyduğunu kontrol etme

Temiz bir belirtim, mock sunucunun da doğru davranmasını sağlar. Bu da frontend ve istemci ekiplerinin güvenilir bir yer tutucu API’ye karşı geliştirme yapmasını mümkün kılar. Bir belirtimin mock akışını nasıl beslediğini görmek için test için bir API'yi taklit etme kılavuzuna bakabilirsiniz.

Önerilen minimum kurulum

Küçük veya orta ölçekli bir ekip için pratik minimum kurulum şöyle olabilir:

Editör:
  Swagger Editor veya entegre API tasarım aracı

CI:
  openapi-spec-validator
  Spectral

Runtime:
  Apidog veya sözleşme testleri
Enter fullscreen mode Exit fullscreen mode

Repository yapısı örneği:

.
├── openapi.yaml
├── .spectral.yaml
└── .github
    └── workflows
        ├── validate-openapi.yml
        └── lint-openapi.yml
Enter fullscreen mode Exit fullscreen mode

Temel akış:

# Şema doğrulaması
openapi-spec-validator openapi.yaml

# Kalite kontrolü
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Pull request merge koşulu:

  • OpenAPI şema doğrulaması geçmeli
  • Lint kuralları geçmeli
  • Sözleşme testleri geçmeli

Bu kurulum basittir, otomatikleştirilebilir ve ekip büyüdükçe genişletilebilir.

Sıkça sorulan sorular

Bir OpenAPI doğrulayıcı ile linter arasındaki fark nedir?

OpenAPI doğrulayıcı, belirtimin OpenAPI şemasına göre yapısal olarak doğru olup olmadığını kontrol eder. Sonuç genellikle geçiş veya hata şeklindedir.

Linter ise kalite ve stil kurallarını kontrol eder. Örneğin her endpoint’in summary içermesi, operationId kullanılması veya path adlandırmasının tutarlı olması gibi kuralları uygular.

Güçlü bir iş akışı ikisini birlikte kullanır.

Bir OpenAPI belirtimini ücretsiz doğrulayabilir miyim?

Evet. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI ve Vacuum ücretsiz ve açık kaynaklı seçeneklerdir. Apidog da ücretsiz katmanında belirtim doğrulaması sağlar ve çalışma zamanı kontrolleri ekler.

Doğrulamayı maliyet nedeniyle atlamak için iyi bir sebep yoktur.

OpenAPI 3.0 ve 3.1’i farklı mı doğrulamalıyım?

Aynı doğrulama yaklaşımını kullanabilirsiniz, ancak sürümü açıkça sabitlemelisiniz. OpenAPI 3.1, JSON Schema ile daha uyumlu hale geldiği için bazı şema davranışları değişmiştir.

Araçlarınızın belirtimde beyan edilen sürümü desteklediğinden emin olun.

Belirtim doğrulaması nerede çalışmalı?

İki yerde çalışmalıdır:

  1. Belirtimi yazarken editörde
  2. Her pull request’te CI içinde

Sadece editör doğrulamasına güvenmek yeterli değildir, çünkü atlanabilir. CI doğrulaması ise merge öncesi zorunlu kapı sağlar.

API’min belirtime uygun olduğunu nasıl kontrol ederim?

Belirtim doğrulaması yalnızca OpenAPI dosyasının doğru olduğunu gösterir. Uygulamanın bu sözleşmeye uyduğunu kanıtlamaz.

Bunu kontrol etmek için canlı API yanıtlarını belirtimdeki şemalarla karşılaştıran sözleşme testleri veya çalışma zamanı doğrulaması çalıştırmalısınız. Apidog bunu doğrudan yapabilir; sözleşme test çerçeveleri de aynı kontrolü test paketi içinde uygulayabilir.

Top comments (0)