OpenAPI Nedir? Swagger ile API Dokümantasyonu

Meta Description

OpenAPI (Swagger) ile API dokümantasyonu oluşturun, sözleşme tabanlı geliştirmeye geçin. Örnek YAML, araçlar ve ipuçları burada.

Giriş (Introduction)

Bir API yazıyorsunuz ama ekipte herkes farklı anlıyor: Frontend “hangi alan zorunlu?” diye soruyor, mobil ekip “hata formatı nedir?” diye bekliyor, QA “senaryoları nasıl çıkaracağım?” diye bocalıyor. Sonuç: yanlış entegrasyonlar, geri dönüşler ve üretimde sürprizler.

OpenAPI tam bu noktada devreye girer: API’nizin tek bir doğru kaynağını (single source of truth) oluşturur. Bu yazıda OpenAPI nedir, Swagger ile nasıl dokümantasyon üretilir, nasıl doğrulanır ve ekip akışına nasıl entegre edilir adım adım göreceksiniz.

OpenAPI Nedir? (API Sözleşmesi Mantığı)

OpenAPI, HTTP API’lerini tanımlamak için kullanılan, dil bağımsız bir spesifikasyondur. Eskiden “Swagger” adıyla bilinse de bugün OpenAPI Specification (OAS) olarak standardize edilmiştir.

OpenAPI ile şunları netleştirirsiniz:

• Endpoint’ler (URL + HTTP method)
• Request/response gövdeleri (JSON şemaları)
• Query/path parametreleri
• Status code’lar ve hata formatı
• Kimlik doğrulama (Bearer, API Key, OAuth2 vb.)

Bunu neden yapmalıyım? Çünkü sözleşme yazınca entegrasyonlar tahmine değil, tanıma dayanır. Üretimde “biz böyle sanmıştık” cümlesi azalır.

OpenAPI ile Neler Kazanırsınız?

Aşağıdaki tablo, OpenAPI’nin pratik faydalarını özetler:

LSI anahtar kelimeler (ilişkili): Swagger UI, API dokümantasyonu, API sözleşmesi, contract-first, schema validation, mock server, code generation.

OpenAPI 3.0 Temelleri: En Küçük Çalışan Örnek

Aşağıdaki örnek, basit bir “sipariş” API’sini OpenAPI 3.0 ile tanımlar. (YAML, okunabilir olduğu için yaygın.)

openapi: 3.0.3
info:
  title: Order API
  version: 1.0.0
  description: Basit sipariş servisi
servers:
  - url: https://api.example.com
paths:
  /orders/{id}:
    get:
      summary: Sipariş detayını getir
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id:
          type: string
          example: "ord_123"
        status:
          type: string
          enum: [CREATED, PAID, SHIPPED, CANCELED]
        total:
          type: number
          format: float
          example: 199.90
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: "ORDER_NOT_FOUND"
        message:
          type: string
          example: "Order not found"

Bu spec size ne verir?

• /orders/{id} endpoint’i, parametreleri ve olası cevapları tek yerde
• Order ve Error şemaları
• Swagger UI ile otomatik dokümantasyon

Swagger UI ile Dokümantasyonu 5 Dakikada Yayına Alın

OpenAPI spec’inizi görsel ve test edilebilir hale getirmenin en pratik yolu Swagger UI.

Seçenek A: Docker ile hızlı kurulum

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/app/openapi.yaml \
  -v $(pwd)/openapi.yaml:/app/openapi.yaml \
  swaggerapi/swagger-ui

Tarayıcıda açın:

• http://localhost:8080

Seçenek B: Uygulamanın içine gömülü servis

Birçok framework (Spring Boot, FastAPI, NestJS) Swagger UI entegrasyonunu hazır getirir. Burada kritik nokta:

• Spec’in otomatik üretildiği yerlerde bile şema ve örnekleri gözden geçirin
• “Her şey otomatik” yaklaşımı, yanlış/eksik doküman riskini artırabilir

Contract-First Yaklaşım: Önce Spec, Sonra Kod

OpenAPI’yi iki şekilde kullanabilirsiniz:

1. Code-first: Koddan doküman üretirsiniz.
2. Contract-first: Önce OpenAPI sözleşmesi yazılır, sonra backend/frontend buna göre geliştirilir.

Neden contract-first daha iyi olabilir?

• API değişiklikleri planlı olur
• Ekipler paralel ilerler
• Geriye dönük uyum (backward compatibility) daha kolay yönetilir

Gerçek hayattan örnek:

• Bir ödeme servisinde amount alanı önce integer (kuruş) iken sonra float’a dönerse, mobil uygulamalar kırılabilir. Contract-first ile bu değişim PR aşamasında görünür olur.

Validation ve CI: “Spec Doğru mu?”yı Otomatik Kontrol Edin

Spec’in var olması yetmez; doğru ve güncel kalması gerekir.

Adım adım önerilen kontrol listesi

1. Spec dosyasını repoya koyun (openapi.yaml)
2. Pull request’te otomatik lint çalıştırın
3. Breaking change kontrolü ekleyin

Popüler araçlar

• Spectral: OpenAPI lint (kural tabanlı)
• openapi-generator: Client/server kod üretimi
• Swagger Editor: Spec yazma ve anında hata görme

Örnek: Spectral ile basit lint

npm i -g @stoplight/spectral-cli
spectral lint openapi.yaml

Bunu neden yapmalıyım? Çünkü doküman “insan disipliniyle” güncel kalmaz. CI ile “sözleşme bozuldu mu?” sorusunu otomatik cevaplarsınız.

OpenAPI ile Mock Server ve Client SDK Üretimi

OpenAPI’nin en büyük pratik faydalarından biri: tek spec’ten farklı çıktılar üretebilmeniz.

Mock server (entegrasyon beklemeden)

• Frontend ekibi backend’i beklemeden ekranları bitirebilir.
• QA test senaryolarını erkenden çıkarabilir.

Client SDK (örnek)

openapi-generator ile TypeScript client üretimi örneği:

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./sdk

Üretilen SDK ile:

• Tip güvenliği artar
• Yanlış endpoint/alan kullanımı azalır

Sık Sorulan Sorular (FAQ)

1) OpenAPI ile Swagger aynı şey mi?

Yakın kavramlar. OpenAPI spesifikasyonun adı, Swagger ise ekosistemdeki araçların (Swagger UI, Swagger Editor) markası gibi düşünebilirsiniz.

2) OpenAPI 2.0 mı 3.0 mı kullanmalıyım?

Yeni projelerde genellikle OpenAPI 3.x önerilir. Daha iyi schema tanımı, content-type yönetimi ve modern ihtiyaçlar için daha uygundur.

3) Dokümantasyonu koddan otomatik üretmek yeterli mi?

Her zaman değil. Otomatik üretim hızlıdır ama örnekler, hata formatı, edge-case açıklamaları çoğu zaman eksik kalır. Kritik alanları elle zenginleştirin.

4) OpenAPI spec’ini nerede tutmalıyım?

En iyi pratik: uygulama reposunda versiyonlu tutmak. Böylece değişiklikler PR ile incelenir ve geri alınabilir.

5) OpenAPI performansı etkiler mi?

Spec bir dokümandır; doğrudan runtime performansı etkilemez. Etki eden kısım, spec’e bağlı çalışan middleware/validation çözümlerinin nasıl kullanıldığıdır.

Sonuç

OpenAPI, API dokümantasyonunu “sonradan yazılan notlar” olmaktan çıkarıp sözleşmeye dönüştürür. Swagger UI ile hızlıca görünür hale getirir, lint/validation ile CI’da güvence altına alır, mock ve SDK üretimiyle ekiplerin paralel çalışmasını sağlar.

Bir sonraki adım: Mevcut API’niz için küçük bir openapi.yaml çıkarın ve önce sadece 1 endpoint ile başlayın. İsterseniz yorumlara kullandığınız stack’i (Node, Java, .NET, Python) yazın; ona uygun en pratik OpenAPI kurulum yolunu önereyim.